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, отображение создается без имени. Избегание использования параметра tagname поможет сохранить совместимость вашего кода между 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 должен быть кратным ALLOCATIONGRANULARITY , которое равно PAGESIZE на системах Unix.

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

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

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

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

write_byte(byte)

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