mmap.md
1> **Источник:** https://python-all.ru/3.3/library/mmap.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 18.6. [`mmap`](https://python-all.ru/3.3/library/mmap.html#module-mmap) – Поддержка файлов, отображаемых в память89Объекты файлов, отображаемых в память, ведут себя и как [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray), и как [*файловые объекты*](https://python-all.ru/3.3/glossary.html#term-file-object). Объекты mmap можно использовать в большинстве мест, где ожидается [`bytearray`](https://python-all.ru/3.3/library/functions.html#bytearray); например, с помощью модуля [`re`](https://python-all.ru/3.3/library/re.html#module-re) можно выполнять поиск по файлу, отображаемому в память. Также можно изменить один байт, выполнив `obj[index] = 97`, или изменить последовательность, присвоив значение срезу: `obj[i1:i2] = b'...'`. Также можно читать и записывать данные, начиная с текущей позиции файла, и перемещаться по файлу с помощью [`seek()`](https://python-all.ru/3.3/library/mmap.html#mmap.seek) в разные позиции.1011Файл, отображаемый в память, создаётся конструктором [`mmap`](https://python-all.ru/3.3/library/mmap.html#module-mmap), который различается в Unix и Windows. В любом случае необходимо предоставить файловый дескриптор файла, открытого для обновления. Если нужно отобразить существующий файловый объект Python, используйте его метод `fileno()`, чтобы получить правильное значение параметра *fileno*. В противном случае можно открыть файл с помощью функции [`os.open()`](https://python-all.ru/3.3/library/os.html#os.open), которая возвращает файловый дескриптор напрямую (файл всё равно нужно будет закрыть по завершении).1213> **Примечание**14>15> Если необходимо создать отображение в память для буферизованного файла, доступного для записи, следует сначала выполнить [`flush()`](https://python-all.ru/3.3/library/io.html#io.IOBase.flush) для этого файла. Это необходимо, чтобы гарантировать, что локальные изменения буферов будут доступны отображению.1617Для обеих версий конструктора (Unix и Windows) *access* может быть указан как необязательный именованный параметр. *access* принимает одно из трёх значений: `ACCESS_READ`, `ACCESS_WRITE` или `ACCESS_COPY`, которые задают соответственно память только для чтения, сквозную запись или копирование при записи. *access* можно использовать как в Unix, так и в Windows. Если *access* не указан, Windows mmap возвращает отображение со сквозной записью. Начальные значения памяти для всех трёх типов доступа берутся из указанного файла. Присваивание отображению памяти с `ACCESS_READ` вызывает исключение [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError). Присваивание отображению памяти с `ACCESS_WRITE` затрагивает как память, так и базовый файл. Присваивание отображению памяти с `ACCESS_COPY` затрагивает память, но не обновляет базовый файл.1819Для отображения анонимной памяти в качестве fileno следует передать -1 вместе с длиной.2021#### `class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset])`2223**(Версия Windows)** Отображает *length* байтов из файла, указанного файловым дескриптором *fileno*, и создаёт объект mmap. Если *length* больше текущего размера файла, файл расширяется до *length* байтов. Если *length* равно `0`, максимальная длина отображения равна текущему размеру файла, за исключением случая, когда файл пуст – тогда Windows вызывает исключение (нельзя создать пустое отображение в Windows).2425*tagname*, если указан и не равен `None`, представляет собой строку, задающую имя тега для отображения. Windows позволяет иметь много разных отображений одного и того же файла. Если указать имя существующего тега, этот тег открывается, в противном случае создаётся новый тег с этим именем. Если этот параметр опущен или равен `None`, отображение создаётся без имени. Отказ от использования параметра tag поможет сохранить переносимость кода между Unix и Windows.2627*offset* может быть задан как неотрицательное целое смещение. Ссылки mmap будут относительными к этому смещению от начала файла. *offset* по умолчанию равен 0. *offset* должен быть кратен ALLOCATIONGRANULARITY.2829#### `class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset])`3031**(Версия Unix)** Отображает *length* байт из файла, заданного файловым дескриптором *fileno*, и возвращает объект mmap. Если *length* равен `0`, максимальная длина отображения будет равна текущему размеру файла на момент вызова [`mmap`](https://python-all.ru/3.3/library/mmap.html#module-mmap).3233*flags* определяет характер отображения. `MAP_PRIVATE` создаёт частное отображение с копированием при записи, поэтому изменения содержимого объекта mmap будут частными для этого процесса, а `MAP_SHARED` создаёт отображение, которое используется совместно со всеми другими процессами, отображающими те же области файла. Значение по умолчанию – `MAP_SHARED`.3435*prot*, если указан, задаёт желаемую защиту памяти; два наиболее полезных значения – `PROT_READ` и `PROT_WRITE`, которые указывают, что страницы можно читать или записывать. *prot* по умолчанию равен `PROT_READ | PROT_WRITE`.3637*access* может быть указан вместо *flags* и *prot* как необязательный именованный параметр. Указывать одновременно *flags*, *prot* и *access* – ошибка. Информацию о том, как использовать этот параметр, см. в описании *access* выше.3839*offset* может быть задан как неотрицательное целое смещение. Ссылки mmap будут относительными к этому смещению от начала файла. *offset* по умолчанию равен 0. *offset* должен быть кратен PAGESIZE или ALLOCATIONGRANULARITY.4041Для обеспечения корректности созданного отображения в память файл, заданный дескриптором *fileno*, внутренне автоматически синхронизируется с физическим хранилищем на Mac OS X и OpenVMS.4243В этом примере показан простой способ использования [`mmap`](https://python-all.ru/3.3/library/mmap.html#module-mmap):4445```python46import mmap4748# записать простой пример файла49with open("hello.txt", "wb") as f:50 f.write(b"Hello Python!\n")5152with open("hello.txt", "r+b") as f:53 # отобразить файл в память, размер 0 означает весь файл54 mm = mmap.mmap(f.fileno(), 0)55 # прочитать содержимое с помощью стандартных методов файла56 print(mm.readline()) # выводит b"Hello Python!\n"57 # чтение содержимого с помощью срезовой нотации58 print(mm[:5]) # выводит b"Hello"59 # обновление содержимого с помощью срезовой нотации;60 # новое содержимое должно быть того же размера61 mm[6:] = b" world!\n"62 # ... и снова прочитать стандартными методами файлов63 mm.seek(0)64 print(mm.readline()) # выводит b"Hello world!\n"65 # закрыть отображение66 mm.close()67```6869[`mmap`](https://python-all.ru/3.3/library/mmap.html#module-mmap) также может использоваться как контекстный менеджер в операторе [`with`](https://python-all.ru/3.3/reference/compound_stmts.html#with):7071```python72import mmap7374with mmap.mmap(-1, 13) as mm:75 mm.write("Hello world!")76```7778Новое в версии 3.2: Поддержка контекстного менеджера.7980Следующий пример демонстрирует, как создать анонимное отображение и обмениваться данными между родительским и дочерним процессами:8182```python83import mmap84import os8586mm = mmap.mmap(-1, 13)87mm.write(b"Hello world!")8889pid = os.fork()9091if pid == 0: # В дочернем процессе92 mm.seek(0)93 print(mm.readline())9495 mm.close()96```9798Объекты файлов с отображением в память поддерживают следующие методы:99100#### `mmap.close()`101102Закрывает mmap. Последующие вызовы других методов объекта приведут к возникновению исключения ValueError. Открытый файл при этом не закрывается.103104#### `mmap.closed`105106`True`, если файл закрыт.107108Новое в версии 3.2.109110#### `mmap.find(sub[, start[, end]])`111112Возвращает наименьший индекс в объекте, где встречается подпоследовательность *sub*, при условии, что *sub* содержится в диапазоне \[*start*, *end*\]. Необязательные аргументы *start* и *end* интерпретируются как в записи среза. В случае неудачи возвращает `-1`.113114#### `mmap.flush([offset[, size]])`115116Сбрасывает изменения, внесённые в копию файла в памяти, обратно на диск. Без вызова этого метода нет гарантии, что изменения будут записаны до уничтожения объекта. Если указаны *offset* и *size*, на диск будут сброшены только изменения в заданном диапазоне байтов; в противном случае сбрасывается вся область отображения.117118**(версия Windows)** Ненулевое возвращённое значение означает успех; нулевое – неудачу.119120**(версия Unix)** Возвращается нулевое значение, означающее успех. При ошибке вызова возбуждается исключение.121122#### `mmap.move(dest, src, count)`123124Копирует *count* байт, начиная со смещения *src*, в целевой индекс *dest*. Если mmap был создан с `ACCESS_READ`, то вызовы move приведут к исключению [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError).125126#### `mmap.read([n])`127128Возвращает [`bytes`](https://python-all.ru/3.3/library/functions.html#bytes), содержащий до *n* байт, начиная с текущей позиции файла. Если аргумент опущен, равен *None* или отрицателен, возвращаются все байты от текущей позиции файла до конца отображения. Позиция файла обновляется и указывает на байт после возвращённых данных.129130Изменено в версии 3.3: Аргумент может быть опущен или равен *None*.131132#### `mmap.read_byte()`133134Возвращает байт в текущей позиции файла в виде целого числа и увеличивает позицию файла на 1.135136#### `mmap.readline()`137138Возвращает одну строку, начиная с текущей позиции в файле и до следующего символа новой строки.139140#### `mmap.resize(newsize)`141142Изменяет размер отображения и базового файла (если он есть). Если mmap был создан с `ACCESS_READ` или `ACCESS_COPY`, изменение размера вызовет исключение [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError).143144#### `mmap.rfind(sub[, start[, end]])`145146Возвращает наибольший индекс в объекте, где найдена подпоследовательность *sub*, такой, что *sub* содержится в диапазоне \[*start*, *end*\]. Необязательные аргументы *start* и *end* интерпретируются как в нотации среза. Возвращает `-1` при неудаче.147148#### `mmap.seek(pos[, whence])`149150Устанавливает текущую позицию файла. Аргумент *whence* является необязательным и по умолчанию равен `os.SEEK_SET` или `0` (абсолютное позиционирование); другие значения: `os.SEEK_CUR` или `1` (смещение относительно текущей позиции) и `os.SEEK_END` или `2` (смещение относительно конца файла).151152#### `mmap.size()`153154Возвращает длину файла, которая может быть больше размера области отображения памяти.155156#### `mmap.tell()`157158Возвращает текущую позицию файлового указателя.159160#### `mmap.write(bytes)`161162Записывает байты из *bytes* в память в текущей позиции файлового указателя; позиция файла обновляется так, чтобы указывать после записанных байтов. Если mmap был создан с `ACCESS_READ`, то запись в него вызовет исключение [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError).163164#### `mmap.write_byte(byte)`165166Записывает целое число *byte* в память в текущей позиции файлового указателя; позиция файла сдвигается на `1`. Если mmap был создан с `ACCESS_READ`, то запись в него вызовет исключение [`TypeError`](https://python-all.ru/3.3/library/exceptions.html#TypeError).167