mmap — Поддержка файлов, отображаемых в памяти¶

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

Чтобы отобразить анонимную память, значение -1 должно быть передано как номер файла вместе с длиной.

class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset])¶

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

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

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

Создает auditing event mmap.__new__ с аргументами fileno, length, access, offset.

class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset])

(Версия для Unix) Отображает длину в байтах из файла, указанного в файловом дескрипторе fileno, и возвращает объект mmap. Если длина равна 0, то максимальная длина карты будет соответствовать текущему размеру файла при вызове mmap.

флаги определяют характер сопоставления. MAP_PRIVATE создает частное сопоставление копирования при записи, поэтому изменения в содержимом объекта mmap будут конфиденциальными для этого процесса, а MAP_SHARED создает сопоставление, которое используется совместно со всеми другими процессами, сопоставляющими те же области файла. Значение по умолчанию - MAP_SHARED. В некоторых системах установлены дополнительные возможные флаги, полный список которых указан в MAP_* constants.

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

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

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

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

Создает auditing event mmap.__new__ с аргументами fileno, length, access, offset.

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

close()¶

Закрывает карту. Последующие вызовы других методов объекта приведут к возникновению исключения 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.

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

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

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

Отправьте ядру сообщение option о области памяти, начинающейся с start и увеличивающей длину в байтах. option должен быть одним из MADV_* constants, доступных в системе. Если значения start и length опущены, то выполняется полное сопоставление. В некоторых системах (включая Linux) значение start должно быть кратно PAGESIZE.

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

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

move(dest, src, count)¶

Скопируйте значение count байт, начинающееся со смещения src, в целевой индекс dest. Если карта была создана с ACCESS_READ, то при вызове функции перемещения возникнет исключение TypeError.

read([n])¶

Возвращает значение bytes, содержащее до n байт, начиная с текущей позиции файла. Если аргумент опущен, None или отрицательный, возвращает все байты от текущей позиции файла до конца сопоставления. Позиция файла обновляется до точки после возвращенных байтов.

Изменено в версии 3.3: Аргумент может быть опущен или None.

read_byte()¶

Возвращает байт в текущей позиции файла в виде целого числа и увеличивает позицию файла на 1.

readline()¶

Возвращает одну строку, начинающуюся с текущей позиции файла и заканчивающуюся следующей новой строкой. Позиция файла обновляется до точки после возвращенных байт.

resize(newsize)¶

Изменяет размер карты и лежащего в ее основе файла, если таковой имеется. Если карта была создана с использованием ACCESS_READ или ACCESS_COPY, при изменении размера карты возникнет исключение TypeError.

В Windows: Изменение размера карты приведет к появлению OSError, если для файла с тем же именем есть другие карты. Изменение размера анонимной карты (т.е. по отношению к файлу подкачки) автоматически создаст новую карту с исходными данными, скопированными до длины нового размера.

Изменено в версии 3.11: Корректный сбой при попытке изменить размер, когда удерживается другая карта, позволяет изменить размер по сравнению с анонимной картой в Windows

rfind(sub[, start[, end]])¶

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

Изменено в версии 3.5: Теперь доступно для записи bytes-like object.

seek(pos[, whence])¶

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

size()¶

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

tell()¶

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

write(bytes)¶

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

Изменено в версии 3.5: Теперь доступно для записи bytes-like object.

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

write_byte(byte)¶

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