mmap – Поддержка файлов с отображением в память¶mmap – Memory-mapped file support

Объекты файлов с отображением в память ведут себя и как 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 отображению памяти влияет на память, но не обновляет базовый файл.

Для отображения анонимной памяти в качестве fileno следует передать -1 вместе с длиной.

class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0, *, trackfd=True)¶

(версия для Windows) Отображает length байт из файла, заданного дескриптором файла fileno, и создаёт объект mmap. Если length больше текущего размера файла, файл расширяется до length байт. Если length равен 0, максимальная длина отображения равна текущему размеру файла, за исключением случая, когда файл пуст: тогда Windows генерирует исключение (нельзя создать пустое отображение в Windows).

tagname, если указан и не равен None, представляет собой строку, задающую имя тега для отображения. Windows позволяет иметь множество разных отображений одного и того же файла. Если указать имя существующего тега, открывается этот тег, иначе создаётся новый тег с таким именем. Если этот параметр опущен или равен None, отображение создаётся без имени. Отказ от использования параметра tagname поможет сохранить переносимость кода между Unix и Windows.

offset может быть указан как неотрицательное целое смещение. Ссылки mmap будут относительными к смещению от начала файла. offset по умолчанию равен 0. offset должен быть кратен ALLOCATIONGRANULARITY.

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

Изменено в версии 3.15: Добавлен параметр trackfd.

Возбуждает событие аудита 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.

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

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

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

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

Изменено в версии 3.13: Добавлен параметр trackfd.

В этом примере показан простой способ использования mmap:

import mmap

# записать простой пример файла
with open("hello.txt", "wb") as f:
    f.write(b"Hello Python!\n")

with open("hello.txt", "r+b") as f:
    # отобразить файл в память, размер 0 означает весь файл
    mm = mmap.mmap(f.fileno(), 0)
    # прочитать содержимое с помощью стандартных методов файла
    print(mm.readline())  # выводит b"Hello Python!\n"
    # чтение содержимого с помощью срезовой нотации
    print(mm[:5])  # выводит b"Hello"
    # обновление содержимого с помощью срезовой нотации;
    # новое содержимое должно быть того же размера
    mm[6:] = b" world!\n"
    # ... и снова прочитать стандартными методами файлов
    mm.seek(0)
    print(mm.readline())  # выводит b"Hello  world!\n"
    # закрыть отображение
    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:  # В дочернем процессе
    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, ]]*, flags=MS_SYNC)¶

Сбрасывает изменения, внесённые в копию файла в памяти, обратно на диск. Без использования этого вызова нет гарантии, что изменения будут записаны до того, как объект будет уничтожен. Если offset и size заданы, на диск будут сброшены только изменения в указанном диапазоне байтов; в противном случае сбрасывается вся область отображения. offset должен быть кратен PAGESIZE или ALLOCATIONGRANULARITY.

Параметр flags задаёт поведение синхронизации. flags должен быть одной из констант MS_*, доступных в системе.

В Windows параметр flags игнорируется.

None возвращается в случае успеха. Исключение возбуждается, если вызов завершился неудачей.

Изменено в версии 3.8: Ранее возвращалось ненулевое значение при успехе; под Windows возвращался нуль при ошибке. Под Unix возвращался нуль при успехе и возбуждалось исключение при ошибке.

Изменено в версии 3.15: Разрешено указывать offset без size. Ранее оба параметра offset и size требовались вместе. Теперь offset можно указывать отдельно, и операция flush будет выполняться от offset до конца mmap.

Изменено в версии 3.15: Добавлен параметр flags для управления поведением синхронизации.

madvise(option[, start[, length]])¶

Отправляет ядру рекомендацию option для области памяти, начинающейся с start и простирающейся на length байт. option должен быть одной из констант MADV_* constants, доступных в системе. Если 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, если существуют другие отображения того же именованного файла. Изменение размера анонимного отображения (т.е. основанного на файле подкачки) беззвучно создаст новое отображение с копией исходных данных до длины нового размера.

Доступность: Windows и системы с системным вызовом mremap().

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

set_name(name, /)¶

Аннотирует отображение памяти заданным name для упрощения идентификации в /proc/<pid>/maps, если ядро поддерживает эту возможность и -X dev передан Python, или если Python собран в режиме отладки. Длина name не должна превышать 67 байт, включая завершающий нулевой символ '\0'.

Доступность: Linux >= 5.17 (ядро, собранное с опцией CONFIG_ANON_VMA_NAME)

Добавлено в версии 3.15.

size()¶

Возвращает длину файла, которая может быть больше размера области, отображаемой в память. Для анонимного отображения возвращает его размер.

Изменено в версии 3.15: Анонимные отображения теперь поддерживаются в Unix.

tell()¶

Возвращает текущую позицию файлового указателя.

write(bytes)¶

Записывает байты из bytes в память в текущей позиции файлового указателя и возвращает количество записанных байт (всегда не меньше len(bytes), так как в случае ошибки записи будет возбуждено исключение ValueError). Позиция файла обновляется и указывает на байт сразу после записанных. Если отображение mmap было создано с ACCESS_READ, то запись в него вызовет исключение TypeError.

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

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

write_byte(byte)¶

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