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.

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

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

Для обеспечения корректности созданного отображения памяти файл, указанный дескриптором 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.

В 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 (перемещение относительно конца файла).

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.