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 не указан, mmap на Windows возвращает отображение с записью через буфер. Начальные значения памяти для всех трёх типов доступа берутся из указанного файла. Присвоение значений в 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: Теперь принимается изменяемый объект типа bytes.

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.

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.

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

write_byte(byte)

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