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=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: Теперь принимаются доступные для записи объекты, подобные bytes.

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: Теперь принимаются доступные для записи объекты, подобные bytes.

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: Теперь принимаются доступные для записи объекты, подобные bytes.

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

write_byte(byte)

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