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, отображение создаётся без имени. Избегайте использования параметра tagname, чтобы ваш код был совместим между 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 version) Картирует length байтов из файла, указанного дескриптором файла fileno, и возвращает объект mmap. Если length равно 0, максимальная длина карты будет соответствовать текущему размеру файла в момент вызова mmap.

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

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.

Данный пример демонстрирует простой способ использования 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.

В Windows: Изменение размера карты вызовет исключение OSError, если существуют другие отображения того же файла. Изменение размера анонимной карты (т.е. по отношению к файлу подкачки) тихо создаст новую карту с исходными данными, скопированными до длины нового размера.

Изменено в версии 3.11: Правильно завершает работу при попытке изменить размер при наличии другого отображения. Разрешает изменение размера анонимной карты в Windows

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.