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=0)

(Версия для 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=0, *, trackfd=True)

(Версия Unix) Картирует 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.

Если trackfd равно False, дескриптор файла, указанный fileno, не будет дублирован, и полученный mmap объект не будет ассоциирован с базовым файлом карты. Это означает, что методы size() и resize() не будут работать. Этот режим полезен для ограничения числа открытых дескрипторов файлов.

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

Изменено в версии 3.13: Добавлен параметр trackfd.

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

Изменяет размер карты и, при необходимости, базового файла.

Изменение размера карты, созданной с access, равным ACCESS_READ или ACCESS_COPY, вызовет исключение TypeError. Изменение размера карты, созданной с trackfd, установленным на False, вызовет исключение ValueError.

В 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 (смещение относительно конца файла).

Изменено в версии 3.13: Возвращает новую абсолютную позицию вместо None.

seekable()

Возвращает, поддерживает ли файл поиск, и возвращаемое значение всегда True.

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

size()

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

tell()

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

write(bytes)

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

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

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

write_byte(byte)

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