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 изменяет память, но не обновляет исходный файл.

Чтобы отобразить анонимную память, вместе с длиной следует передать в качестве fileno значение -1.

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.

Вместо параметров flags и prot можно указать необязательный именованный параметр access. Одновременное указание flags, prot и access является ошибкой. Информацию об использовании этого параметра см. в приведённом выше описании access.

Параметр offset можно указать как неотрицательное целое смещение. Все обращения к mmap будут отсчитываться от смещения относительно начала файла. По умолчанию offset равен 0. Значение offset должно быть кратно ALLOCATIONGRANULARITY, которая в системах Unix равна PAGESIZE.

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

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

Изменено в версии 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()

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). Позиция файла обновляется и указывает на байт после записанных данных. Если mmap создан с параметром ACCESS_READ, попытка записи вызывает исключение TypeError.

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

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

write_byte(byte)

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