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

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

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.

prot, если указано, задаёт желаемую защиту памяти; два наиболее полезных значения — PROT_READ и PROT_WRITE, чтобы указать, что страницы могут быть читаемы или записываемы. prot по умолчанию равно PROT_READ | PROT_WRITE.

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

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

Для обеспечения валидности созданной карты памяти файл, указанный дескриптором fileno, автоматически синхронизируется с физическим носителем на Mac OS X и OpenVMS.

Этот пример демонстрирует простой способ использования 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()

Объекты файлов с отображением в памяти поддерживают следующие методы:

close()

Закрывает mmap. Последующие вызовы других методов объекта приведут к возбуждению исключения ValueError. Это не закроет открытый файл.

closed

True если файл закрыт.

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

find(sub[, start[, end]])

Возвращает наименьший индекс в объекте, где подпоследовательность sub найдена, так что sub содержится в диапазоне [start, end]. Необязательные аргументы start и end интерпретируются как в записи срезов. Возвращает -1 при неудаче.

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

flush([offset[, size]])

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

(Версия Windows) ненулевое значение указывает на успех; нулевое значение — на неудачу.

(Версия Unix) нулевое значение возвращается для указания успеха. При неудаче вызова возбуждается исключение.

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-like object.

seek(pos[, whence])

Устанавливает текущую позицию файла. Аргумент whence необязателен и по умолчанию равен os.SEEK_SET или 0 (абсолютное позиционирование файла); другие значения — os.SEEK_CUR или 1 (поиск относительно текущей позиции) и os.SEEK_END или 2 (поиск относительно конца файла).

size()

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

tell()

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

write(bytes)

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

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

write_byte(byte)

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