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, отображение создается без имени. Избегание использования параметра тега поможет сохранить совместимость вашего кода между Unix и Windows.

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

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, внутри автоматически синхронизируется с физическим хранилищем на 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()

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

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.

(Версия Windows) ненулевое значение возвращает успех; ноль — неудачу.

(Версия Unix) Возвращаемое значение 0 означает успех. При неудаче вызывается исключение.

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.