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) Картирует 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.