`mmap.md`

363 строк · 28.9 КБ · обычная страница · сырой текст · скачать
1> **Источник:** https://python-all.ru/3.16/library/mmap.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `mmap` – Поддержка файлов с отображением в память89---1011[Доступность](https://python-all.ru/3.16/library/intro.html#availability): не WASI.1213Этот модуль не работает или недоступен на WebAssembly. Подробнее см. [платформы WebAssembly](https://python-all.ru/3.16/library/intro.html#wasm-availability).1415Объекты файлов с отображением в память ведут себя и как [`bytearray`](https://python-all.ru/3.16/library/stdtypes.html#bytearray), и как [файловые объекты](https://python-all.ru/3.16/glossary.html#term-file-object). Объекты mmap можно использовать почти везде, где ожидаются `bytearray`; например, можно использовать модуль [`re`](https://python-all.ru/3.16/library/re.html#module-re) для поиска в файле с отображением в память. Также можно изменить один байт, выполнив `obj[index] = 97`, или изменить подпоследовательность, присвоив значение срезу: `obj[i1:i2] = b'...'`. Кроме того, можно читать и записывать данные, начиная с текущей позиции в файле, и `seek()` по файлу в разные позиции.1617Файл с отображением в память создаётся конструктором [`mmap`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap), который отличается на Unix и Windows. В любом случае необходимо предоставить файловый дескриптор файла, открытого для обновления. Если требуется отобразить существующий файловый объект Python, используйте его метод [`fileno()`](https://python-all.ru/3.16/library/io.html#io.IOBase.fileno), чтобы получить правильное значение параметра *fileno*. В противном случае можно открыть файл с помощью функции [`os.open()`](https://python-all.ru/3.16/library/os.html#os.open), которая напрямую возвращает файловый дескриптор (файл всё равно нужно закрыть после использования).1819> **Примечание**20>21> Если нужно создать отображение в память для буферизованного файла, доступного для записи, сначала следует [`flush()`](https://python-all.ru/3.16/library/io.html#io.IOBase.flush) файл. Это необходимо, чтобы локальные изменения в буферах были доступны для отображения.2223Для версий конструктора как для Unix, так и для Windows, *access* может быть указан как необязательный именованный параметр. *access* принимает одно из четырёх значений: `ACCESS_READ`, `ACCESS_WRITE` или `ACCESS_COPY` для указания памяти только для чтения, сквозной записи или копирования при записи соответственно, или `ACCESS_DEFAULT`, чтобы обратиться к *prot*. *access* можно использовать как в Unix, так и в Windows. Если *access* не задан, Windows mmap возвращает отображение со сквозной записью. Начальные значения памяти для всех трёх типов доступа берутся из указанного файла. Присваивание `ACCESS_READ` отображению памяти вызывает исключение [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). Присваивание `ACCESS_WRITE` отображению памяти влияет и на память, и на базовый файл. Присваивание `ACCESS_COPY` отображению памяти влияет на память, но не обновляет базовый файл.2425Изменено в версии 3.7: Добавлена константа `ACCESS_DEFAULT`.2627Для отображения анонимной памяти в качестве fileno следует передать -1 вместе с длиной.2829#### `class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0, *, trackfd=True)`3031**(версия для Windows)** Отображает *length* байт из файла, заданного дескриптором файла *fileno*, и создаёт объект mmap. Если *length* больше текущего размера файла, файл расширяется до *length* байт. Если *length* равен `0`, максимальная длина отображения равна текущему размеру файла, за исключением случая, когда файл пуст: тогда Windows генерирует исключение (нельзя создать пустое отображение в Windows).3233*tagname*, если указан и не равен `None`, представляет собой строку, задающую имя тега для отображения. Windows позволяет иметь множество разных отображений одного и того же файла. Если указать имя существующего тега, открывается этот тег, иначе создаётся новый тег с таким именем. Если этот параметр опущен или равен `None`, отображение создаётся без имени. Отказ от использования параметра *tagname* поможет сохранить переносимость кода между Unix и Windows.3435*offset* может быть указан как неотрицательное целое смещение. Ссылки mmap будут относительными к смещению от начала файла. *offset* по умолчанию равен 0. *offset* должен быть кратен `ALLOCATIONGRANULARITY`.3637Если *trackfd* равен `False`, дескриптор файла, соответствующий *fileno*, не будет дублироваться, и полученный объект `mmap` не будет связан с базовым файлом отображения. Это означает, что методы [`size()`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap.size) и [`resize()`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap.resize) завершатся ошибкой. Этот режим полезен для ограничения количества открытых дескрипторов. Исходный файл можно переименовать (но не удалить) после закрытия *fileno*.3839Изменено в версии 3.15: Добавлен параметр *trackfd*.4041Возбуждает [событие аудита](https://python-all.ru/3.16/library/sys.html#auditing) `mmap.__new__` с аргументами `fileno`, `length`, `access`, `offset`.4243#### `class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE | PROT_READ, access=ACCESS_DEFAULT, offset=0, *, trackfd=True)`4445**(Версия Unix)** Отображает *length* байтов из файла, указанного файловым дескриптором *fileno*, и возвращает объект mmap. Если *length* равно `0`, максимальная длина отображения будет равна текущему размеру файла на момент вызова [`mmap`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap).4647*flags* задаёт характер отображения. [`MAP_PRIVATE`](https://python-all.ru/3.16/library/mmap.html#mmap.MAP_PRIVATE) создаёт частное отображение с копированием при записи, поэтому изменения содержимого объекта mmap будут приватными для этого процесса, а [`MAP_SHARED`](https://python-all.ru/3.16/library/mmap.html#mmap.MAP_SHARED) создаёт отображение, разделяемое со всеми другими процессами, отображающими те же области файла. Значение по умолчанию – `MAP_SHARED`. В некоторых системах есть дополнительные возможные флаги; полный список указан в [константах MAP\_\*](https://python-all.ru/3.16/library/mmap.html#map-constants).4849*prot*, если указан, задаёт желаемую защиту памяти; два наиболее полезных значения – `PROT_READ` и `PROT_WRITE`, чтобы указать, что страницы можно читать или записывать. *prot* по умолчанию равен `PROT_READ | PROT_WRITE`.5051*access* может быть указан вместо *flags* и *prot* как необязательный именованный параметр. Указывать одновременно *flags*, *prot* и *access* – ошибка. Информацию о том, как использовать этот параметр, см. в описании *access* выше.5253*offset* может быть указан как неотрицательное целое смещение. Ссылки mmap будут относительными к смещению от начала файла. *offset* по умолчанию равен 0. *offset* должен быть кратен `ALLOCATIONGRANULARITY`, что в системах Unix равно `PAGESIZE`.5455Если *trackfd* равен `False`, файловый дескриптор, указанный *fileno*, не будет дублироваться, и результирующий объект `mmap` не будет связан с базовым файлом отображения. Это означает, что методы [`size()`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap.size) и [`resize()`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap.resize) завершатся ошибкой. Этот режим полезен для ограничения количества открытых файловых дескрипторов.5657Чтобы обеспечить корректность созданного отображения памяти, файл, указанный дескриптором *fileno*, на macOS автоматически синхронизируется с физическим хранилищем.5859Изменено в версии 3.13: Добавлен параметр *trackfd*.6061В этом примере показан простой способ использования [`mmap`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap):6263```python64import mmap6566# записать простой пример файла67with open("hello.txt", "wb") as f:68    f.write(b"Hello Python!\n")6970with open("hello.txt", "r+b") as f:71    # отобразить файл в память, размер 0 означает весь файл72    mm = mmap.mmap(f.fileno(), 0)73    # прочитать содержимое с помощью стандартных методов файла74    print(mm.readline())  # выводит b"Hello Python!\n"75    # чтение содержимого с помощью срезовой нотации76    print(mm[:5])  # выводит b"Hello"77    # обновление содержимого с помощью срезовой нотации;78    # новое содержимое должно быть того же размера79    mm[6:] = b" world!\n"80    # ... и снова прочитать стандартными методами файлов81    mm.seek(0)82    print(mm.readline())  # выводит b"Hello  world!\n"83    # закрыть отображение84    mm.close()85```8687[`mmap`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap) также можно использовать как контекстный менеджер в операторе [`with`](https://python-all.ru/3.16/reference/compound_stmts.html#with):8889```python90import mmap9192with mmap.mmap(-1, 13) as mm:93    mm.write(b"Hello world!")94```9596Добавлено в версии 3.2: Поддержка контекстного менеджера.9798Следующий пример демонстрирует, как создать анонимное отображение и обмениваться данными между родительским и дочерним процессами:99100```python101import mmap102import os103104mm = mmap.mmap(-1, 13)105mm.write(b"Hello world!")106107pid = os.fork()108109if pid == 0:  # В дочернем процессе110    mm.seek(0)111    print(mm.readline())112113    mm.close()114```115116Возбуждает [событие аудита](https://python-all.ru/3.16/library/sys.html#auditing) `mmap.__new__` с аргументами `fileno`, `length`, `access`, `offset`.117118Объекты файлов с отображением в память поддерживают следующие методы:119120#### `close()`121122Закрывает mmap. Последующие вызовы других методов объекта приведут к возникновению исключения ValueError. Открытый файл при этом не закрывается.123124#### `closed`125126`True`, если файл закрыт.127128Добавлено в версии 3.2.129130#### `find(sub[, start[, end]])`131132Возвращает наименьший индекс в объекте, где встречается подпоследовательность *sub*, при условии, что *sub* содержится в диапазоне \[*start*, *end*\]. Необязательные аргументы *start* и *end* интерпретируются как в записи среза. В случае неудачи возвращает `-1`.133134Изменено в версии 3.5: Теперь принимается записываемый [байтоподобный объект](https://python-all.ru/3.16/glossary.html#term-bytes-like-object).135136#### `flush([offset, [size, ]]*, flags=MS_SYNC)`137138Сбрасывает изменения, внесённые в копию файла в памяти, обратно на диск. Без использования этого вызова нет гарантии, что изменения будут записаны до того, как объект будет уничтожен. Если *offset* и *size* заданы, на диск будут сброшены только изменения в указанном диапазоне байтов; в противном случае сбрасывается вся область отображения. *offset* должен быть кратен `PAGESIZE` или `ALLOCATIONGRANULARITY`.139140Параметр *flags* задаёт поведение синхронизации. *flags* должен быть одной из [констант MS\_\*](https://python-all.ru/3.16/library/mmap.html#ms-constants), доступных в системе.141142В Windows параметр *flags* игнорируется.143144`None` возвращается в случае успеха. Исключение возбуждается, если вызов завершился неудачей.145146Изменено в версии 3.8: Ранее возвращалось ненулевое значение при успехе; под Windows возвращался нуль при ошибке. Под Unix возвращался нуль при успехе и возбуждалось исключение при ошибке.147148Изменено в версии 3.15: Разрешено указывать *offset* без *size*. Ранее оба параметра *offset* и *size* требовались вместе. Теперь *offset* можно указывать отдельно, и операция flush будет выполняться от *offset* до конца mmap.149150Изменено в версии 3.15: Добавлен параметр *flags* для управления поведением синхронизации.151152#### `madvise(option[, start[, length]])`153154Отправляет ядру рекомендацию *option* для области памяти, начинающейся с *start* и простирающейся на *length* байт. *option* должен быть одной из констант [MADV\_\* constants](https://python-all.ru/3.16/library/mmap.html#madvise-constants), доступных в системе. Если *start* и *length* опущены, затрагивается всё отображение. На некоторых системах (включая Linux) *start* должен быть кратен `PAGESIZE`.155156Доступность: системы с системным вызовом `madvise()`.157158Добавлено в версии 3.8.159160#### `move(dest, src, count)`161162Копирует *count* байт, начиная со смещения *src*, в индекс назначения *dest*. Если mmap был создан с `ACCESS_READ`, то вызовы move вызовут исключение [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError).163164#### `read([n])`165166Возвращает [`bytes`](https://python-all.ru/3.16/library/stdtypes.html#bytes), содержащий до *n* байт, начиная с текущей позиции в файле. Если аргумент опущен, равен `None` или отрицательному значению, возвращаются все байты от текущей позиции до конца отображения. Позиция в файле обновляется так, чтобы указывать на байты после возвращённых.167168Изменено в версии 3.3: Аргумент можно опустить или задать `None`.169170#### `read_byte()`171172Возвращает байт в текущей позиции файла в виде целого числа и увеличивает позицию файла на 1.173174#### `readline()`175176Возвращает одну строку, начиная с текущей позиции файла и до следующего символа новой строки. Позиция файла обновляется так, чтобы указывать на байты после возвращённых.177178#### `resize(newsize)`179180Изменяет размер отображения и соответствующего файла, если он существует.181182Изменение размера отображения, созданного с *access* равным `ACCESS_READ` или `ACCESS_COPY`, вызовет исключение [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError). Изменение размера отображения, созданного с *trackfd*, установленным в `False`, вызовет исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError).183184**В Windows**: изменение размера отображения вызовет [`OSError`](https://python-all.ru/3.16/library/exceptions.html#OSError), если существуют другие отображения того же именованного файла. Изменение размера анонимного отображения (т.е. основанного на файле подкачки) беззвучно создаст новое отображение с копией исходных данных до длины нового размера.185186Доступность: Windows и системы с системным вызовом `mremap()`.187188Изменено в версии 3.11: Корректно завершается ошибкой при попытке изменить размер, если удерживается другое отображение. Разрешает изменение размера анонимного отображения в Windows.189190#### `rfind(sub[, start[, end]])`191192Возвращает наибольший индекс в объекте, где найдена подпоследовательность *sub*, такой, что *sub* содержится в диапазоне \[*start*, *end*\]. Необязательные аргументы *start* и *end* интерпретируются как в нотации среза. Возвращает `-1` при неудаче.193194Изменено в версии 3.5: Теперь принимается записываемый [байтоподобный объект](https://python-all.ru/3.16/glossary.html#term-bytes-like-object).195196#### `seek(pos[, whence])`197198Устанавливает текущую позицию в файле. Аргумент *whence* необязателен и по умолчанию равен `os.SEEK_SET` или `0` (абсолютное позиционирование); другие значения: `os.SEEK_CUR` или `1` (смещение относительно текущей позиции) и `os.SEEK_END` или `2` (смещение относительно конца файла).199200Изменено в версии 3.13: Возвращает новую абсолютную позицию вместо `None`.201202#### `seekable()`203204Возвращает, поддерживает ли файл позиционирование; возвращаемое значение всегда `True`.205206Добавлено в версии 3.13.207208#### `set_name(name, /)`209210Аннотирует отображение памяти заданным *name* для упрощения идентификации в `/proc/<pid>/maps`, если ядро поддерживает эту возможность и [`-X dev`](https://python-all.ru/3.16/using/cmdline.html#cmdoption-X) передан Python, или если Python собран в [режиме отладки](https://python-all.ru/3.16/using/configure.html#debug-build). Длина *name* не должна превышать 67 байт, включая завершающий нулевой символ `'\0'`.211212[Доступность](https://python-all.ru/3.16/library/intro.html#availability): Linux \>= 5.17 (ядро, собранное с опцией `CONFIG_ANON_VMA_NAME`)213214Добавлено в версии 3.15.215216#### `size()`217218Возвращает длину файла, которая может быть больше размера области, отображаемой в память. Для анонимного отображения возвращает его размер.219220Изменено в версии 3.15: Анонимные отображения теперь поддерживаются в Unix.221222#### `tell()`223224Возвращает текущую позицию файлового указателя.225226#### `write(bytes)`227228Записывает байты из *bytes* в память в текущей позиции файлового указателя и возвращает количество записанных байт (всегда не меньше `len(bytes)`, так как в случае ошибки записи будет возбуждено исключение [`ValueError`](https://python-all.ru/3.16/library/exceptions.html#ValueError)). Позиция файла обновляется и указывает на байт сразу после записанных. Если отображение mmap было создано с `ACCESS_READ`, то запись в него вызовет исключение [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError).229230Изменено в версии 3.5: Теперь принимается записываемый [байтоподобный объект](https://python-all.ru/3.16/glossary.html#term-bytes-like-object).231232Изменено в версии 3.6: Теперь возвращается количество записанных байт.233234#### `write_byte(byte)`235236Записывает целое число *byte* в память в текущей позиции файлового указателя; позиция файла увеличивается на `1`. Если отображение mmap было создано с `ACCESS_READ`, то запись в него вызовет исключение [`TypeError`](https://python-all.ru/3.16/library/exceptions.html#TypeError).237238## Константы MADV\_\*239240#### `mmap.MADV_NORMAL`241242#### `mmap.MADV_RANDOM`243244#### `mmap.MADV_SEQUENTIAL`245246#### `mmap.MADV_WILLNEED`247248#### `mmap.MADV_DONTNEED`249250#### `mmap.MADV_REMOVE`251252#### `mmap.MADV_DONTFORK`253254#### `mmap.MADV_DOFORK`255256#### `mmap.MADV_HWPOISON`257258#### `mmap.MADV_MERGEABLE`259260#### `mmap.MADV_UNMERGEABLE`261262#### `mmap.MADV_SOFT_OFFLINE`263264#### `mmap.MADV_HUGEPAGE`265266#### `mmap.MADV_NOHUGEPAGE`267268#### `mmap.MADV_DONTDUMP`269270#### `mmap.MADV_DODUMP`271272#### `mmap.MADV_FREE`273274#### `mmap.MADV_NOSYNC`275276#### `mmap.MADV_AUTOSYNC`277278#### `mmap.MADV_NOCORE`279280#### `mmap.MADV_CORE`281282#### `mmap.MADV_PROTECT`283284#### `mmap.MADV_FREE_REUSABLE`285286#### `mmap.MADV_FREE_REUSE`287288Эти параметры можно передать [`mmap.madvise()`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap.madvise). Не все параметры доступны на всех системах.289290Доступность: системы с системным вызовом madvise().291292Добавлено в версии 3.8.293294## Константы MAP\_\*295296#### `mmap.MAP_SHARED`297298#### `mmap.MAP_PRIVATE`299300#### `mmap.MAP_32BIT`301302#### `mmap.MAP_ALIGNED_SUPER`303304#### `mmap.MAP_ANON`305306#### `mmap.MAP_ANONYMOUS`307308#### `mmap.MAP_CONCEAL`309310#### `mmap.MAP_DENYWRITE`311312#### `mmap.MAP_EXECUTABLE`313314#### `mmap.MAP_HASSEMAPHORE`315316#### `mmap.MAP_JIT`317318#### `mmap.MAP_NOCACHE`319320#### `mmap.MAP_NOEXTEND`321322#### `mmap.MAP_NORESERVE`323324#### `mmap.MAP_POPULATE`325326#### `mmap.MAP_RESILIENT_CODESIGN`327328#### `mmap.MAP_RESILIENT_MEDIA`329330#### `mmap.MAP_STACK`331332#### `mmap.MAP_TPRO`333334#### `mmap.MAP_TRANSLATED_ALLOW_EXECUTE`335336#### `mmap.MAP_UNIX03`337338Это различные флаги, которые можно передать [`mmap.mmap()`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap). `MAP_ALIGNED_SUPER` доступен только во FreeBSD, а `MAP_CONCEAL` – только в OpenBSD. Учтите, что некоторые параметры могут отсутствовать на отдельных системах.339340Изменено в версии 3.10: Добавлена константа `MAP_POPULATE`.341342Добавлено в версии 3.11: Добавлена константа `MAP_STACK`.343344Добавлено в версии 3.12: Добавлены константы `MAP_ALIGNED_SUPER` и `MAP_CONCEAL`.345346Добавлено в версии 3.13: Добавлены константы `MAP_32BIT`, `MAP_HASSEMAPHORE`, `MAP_JIT`, `MAP_NOCACHE`, `MAP_NOEXTEND`, `MAP_NORESERVE`, `MAP_RESILIENT_CODESIGN`, `MAP_RESILIENT_MEDIA`, `MAP_TPRO`, `MAP_TRANSLATED_ALLOW_EXECUTE` и `MAP_UNIX03`.347348## Константы MS\_\*349350#### `mmap.MS_SYNC`351352#### `mmap.MS_ASYNC`353354#### `mmap.MS_INVALIDATE`355356Эти флаги управляют поведением синхронизации для [`mmap.flush()`](https://python-all.ru/3.16/library/mmap.html#mmap.mmap.flush):357358- `MS_SYNC` – синхронный сброс: запись планируется и вызов блокируется до тех пор, пока данные не будут физически записаны на носитель.359- `MS_ASYNC` – асинхронный сброс: запись планируется, но вызов возвращается немедленно, не дожидаясь завершения.360- `MS_INVALIDATE` – инвалидация кэшированных данных: делает другие отображения того же файла недействительными, чтобы они увидели изменения.361362Добавлено в версии 3.15.363