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 version) Картирует 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, внутренне автоматически синхронизируется с физическим хранилищем на Mac OS X и 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: Теперь принимается записываемый объект типа bytes-like object.

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: Теперь принимается записываемый объект типа bytes-like object.

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: Теперь принимается записываемый объект типа bytes-like object.

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

write_byte(byte)

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