mmap — Поддержка файлов с отображением в память

Объекты файлов с отображением в память ведут себя как bytearray и как объекты файлов. Вы можете использовать объекты mmap в большинстве мест, где ожидаются bytearray; например, вы можете использовать модуль re для поиска в файле с отображением в память. Вы также можете изменить один байт, выполнив obj[index] = 97, или изменить подпоследовательность, присвоив значение срезу: obj[i1:i2] = b'...'. Также вы можете читать и записывать данные, начиная с текущей позиции файла, и seek() по файлу в разные позиции.

Файл с отображением в память создается конструктором mmap, который отличается на Unix и Windows. В любом случае вам необходимо предоставить дескриптор файла, открытого для обновления. Если вы хотите отобразить существующий объект файла Python, используйте его метод fileno() для получения правильного значения для параметра fileno. В противном случае вы можете открыть файл с помощью функции os.open(), которая возвращает дескриптор файла непосредственно (файл все равно необходимо закрыть по окончании работы).

Для обоих версий конструктора (Unix и Windows) access может быть указан как необязательный параметр ключевого слова. access принимает одно из четырёх значений: ACCESS_READ, ACCESS_WRITE, или ACCESS_COPY для указания соответственно только для чтения, для записи с прохождением или для копирования при записи, или ACCESS_DEFAULT для отсрочки до prot. access может использоваться как на Unix, так и на Windows. Если access не указан, Windows mmap возвращает отображение для записи с прохождением. Начальные значения памяти для всех трёх типов доступа берутся из указанного файла. Присвоение значения в ACCESS_READ отображении в памяти вызывает исключение TypeError. Присвоение значения в ACCESS_WRITE отображении в памяти влияет как на память, так и на базовый файл. Присвоение значения в ACCESS_COPY отображении в памяти влияет на память, но не обновляет базовый файл.

Для отображения анонимной памяти -1 должен быть передан как fileno вместе с длиной.

class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset])

(Версия для Windows) Отображает length байтов из файла, указанного дескриптором файла fileno, и создаёт объект mmap. Если length больше текущего размера файла, файл расширяется до length байтов. Если length 0, максимальная длина отображения — текущий размер файла, за исключением того, что если файл пустой, Windows вызывает исключение (вы не можете создать пустое отображение на Windows).

tagname, если указан и не None, — строка, задающая имя тега для отображения. Windows позволяет иметь множество различных отображений для одного файла. Если вы указываете имя существующего тега, этот тег открывается; в противном случае создаётся новый тег с этим именем. Если этот параметр опущен или None, отображение создаётся без имени. Избегание использования параметра tag поможет сохранить совместимость вашего кода между Unix и Windows.

offset может быть указан как неотрицательное целое смещение. Ссылки mmap будут относиться к смещению от начала файла. offset по умолчанию равен 0. offset должен быть кратным ALLOCATIONGRANULARITY.

Вызывает событие аудита аудита mmap.__new__ с аргументами fileno, length, access, offset.

class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset])

(Unix версия) Картирует length байтов из файла, указанного дескриптором файла fileno, и возвращает объект mmap. Если length равно 0, максимальная длина карты будет равна текущему размеру файла в момент вызова mmap.

flags определяет характер отображения. MAP_PRIVATE создаёт частное отображение с копированием при записи, поэтому изменения содержимого объекта mmap будут приватными для данного процесса, а MAP_SHARED создаёт отображение, которое разделяется со всеми другими процессами, отображающими те же области файла. Значение по умолчанию равно MAP_SHARED.

prot, если указано, задаёт желаемую защиту памяти; две наиболее полезные значения — PROT_READ и PROT_WRITE, чтобы указать, что страницы могут быть прочитаны или записаны. Значение prot по умолчанию — PROT_READ | PROT_WRITE.

access можно указать вместо flags и prot в качестве необязательного ключевого параметра. Ошибка произойдёт, если будут указаны все три параметра: flags, prot и access. См. описание access выше для получения информации о том, как использовать этот параметр.

offset может быть указан как неотрицательное смещение. Ссылка mmap будет относительной к смещению от начала файла. Значение offset по умолчанию равно 0. offset должен быть кратен ALLOCATIONGRANULARITY, что равно PAGESIZE на Unix-системах.

Для обеспечения корректности созданной памяти, файл, указанный дескриптором fileno, внутри автоматически синхронизируется с физическим носителем на macOS и OpenVMS.

Этот пример демонстрирует простой способ использования mmap:

import mmap

# write a simple example file
with open("hello.txt", "wb") as f:
    f.write(b"Hello Python!\n")

with open("hello.txt", "r+b") as f:
    # memory-map the file, size 0 means whole file
    mm = mmap.mmap(f.fileno(), 0)
    # read content via standard file methods
    print(mm.readline())  # prints b"Hello Python!\n"
    # read content via slice notation
    print(mm[:5])  # prints b"Hello"
    # update content using slice notation;
    # note that new content must have same size
    mm[6:] = b" world!\n"
    # ... and read again using standard file methods
    mm.seek(0)
    print(mm.readline())  # prints b"Hello  world!\n"
    # close the map
    mm.close()

mmap также может использоваться как менеджер контекста в инструкции with:

import mmap

with mmap.mmap(-1, 13) as mm:
    mm.write(b"Hello world!")

Добавлен в версии 3.2: Поддержка менеджера контекста.

Следующий пример демонстрирует, как создать анонимную карту и обмениваться данными между родительским и дочерним процессами:

import mmap
import os

mm = mmap.mmap(-1, 13)
mm.write(b"Hello world!")

pid = os.fork()

if pid == 0:  # In a child process
    mm.seek(0)
    print(mm.readline())

    mm.close()

Вызывает событие аудита аудита mmap.__new__ с аргументами fileno, length, access, offset.

Объекты отображения файлов памяти поддерживают следующие методы:

close()

Закрывает mmap. Последующие вызовы других методов объекта приведут к возбуждению исключения ValueError. Файл не будет закрыт.

closed

True если файл закрыт.

Добавлен в версии 3.2.

find(sub[, start[, end]])

Возвращает наименьший индекс в объекте, где подпоследовательность sub найдена, так что sub содержится в диапазоне [start, end]. Необязательные аргументы start и end интерпретируются как в обозначениях срезов. В случае неудачи возвращает -1.

Изменено в версии 3.5: Теперь принимается записываемый объект-подобный байтам.

flush([offset[, size]])

Сохраняет изменения, внесённые в копию файла в памяти, обратно на диск. Без использования этого вызова нет гарантии, что изменения будут записаны обратно перед уничтожением объекта. Если указаны offset и size, только изменения в заданном диапазоне байтов будут сохранены на диск; в противном случае весь объём отображения сохраняется. offset должен быть кратен PAGESIZE или ALLOCATIONGRANULARITY.

None возвращается для обозначения успеха. Исключение генерируется, когда вызов завершился неудачей.

Изменено в версии 3.8: Ранее ненулевое значение возвращалось при успехе; ноль возвращался при ошибке в Windows. Ноль возвращался при успехе; исключение генерировалось при ошибке в Unix.

madvise(option[, start[, length]])

Отправляет подсказку option ядру о области памяти, начиная с start и охватывая length байтов. option должен быть одним из констант MADV_*, доступных в системе. Если start и length опущены, весь объём отображения охватывается. На некоторых системах (включая Linux), start должен быть кратен PAGESIZE.

Доступность: Системы с системным вызовом madvise().

Добавлен в версии 3.8.

move(dest, src, count)

Копирует count байт, начиная со смещения src, в целевой индекс dest. Если mmap был создан с ACCESS_READ, тогда вызовы move будут генерировать исключение TypeError.

read([n])

Возвращает bytes содержащий до n байтов, начиная с текущей позиции файла. Если аргумент опущен, None или отрицательный, возвращает все байты от текущей позиции файла до конца отображения. Позиция файла обновляется так, чтобы указывать на байты после возвращённых.

Изменено в версии 3.3: Аргумент может быть опущен или None.

read_byte()

Возвращает байт в текущей позиции файла как целое число и передвигает позицию файла на 1.

readline()

Возвращает одну строку, начиная с текущей позиции файла и до следующей новой строки. Позиция файла обновляется так, чтобы указывать на байты после возвращённых.

resize(newsize)

Изменяет размер карты и соответствующего файла, если таковой имеется. Если mmap был создан с ACCESS_READ или ACCESS_COPY, изменение размера карты вызовет исключение TypeError.

rfind(sub[, start[, end]])

Возвращает наивысший индекс в объекте, где подпоследовательность sub найдена, так что sub содержится в диапазоне [start, end]. Необязательные аргументы start и end интерпретируются как в обозначениях срезов. В случае неудачи возвращает -1.

Изменено в версии 3.5: Теперь принимается записываемый объект-подобный байтам.

seek(pos[, whence])

Устанавливает текущую позицию файла. Аргумент whence необязателен и по умолчанию равен os.SEEK_SET или 0 (абсолютное позиционирование файла); другие значения равны os.SEEK_CUR или 1 (поиск относительно текущей позиции) и os.SEEK_END или 2 (поиск относительно конца файла).

size()

Возвращает длину файла, которая может быть больше размера области отображения памяти.

tell()

Возвращает текущую позицию указателя файла.

write(bytes)

Записывает байты в bytes в память по текущей позиции указателя файла и возвращает количество записанных байтов (никогда меньше len(bytes), так как если запись завершается неудачей, будет возбуждено исключение ValueError). Позиция файла обновляется так, чтобы указывать на байты после записанных. Если mmap был создан с ACCESS_READ, то запись в него вызовет исключение TypeError.

Изменено в версии 3.5: Теперь принимается записываемый объект-подобный байтам.

Изменено в версии 3.6: Теперь возвращается число записанных байтов.

write_byte(byte)

Записывает целое число byte в память по текущей позиции указателя файла; позиция файла перемещается на 1. Если mmap был создан с ACCESS_READ, то запись в него вызовет исключение TypeError.