mmap.md
1> **Источник:** https://python-all.ru/3.1/library/mmap.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# 16.4. `mmap` – Поддержка файлов, отображаемых в память89Объекты файлов, отображаемых в память, ведут себя и как [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray), и как [*файловые объекты*](https://python-all.ru/3.1/glossary.html#term-file-object). Объекты mmap можно использовать в большинстве мест, где ожидается [`bytearray`](https://python-all.ru/3.1/library/functions.html#bytearray); например, с помощью модуля [`re`](https://python-all.ru/3.1/library/re.html#module-re) можно выполнять поиск по файлу, отображаемому в память. Также можно изменить один байт, выполнив `obj[index] = 97`, или изменить последовательность, присвоив значение срезу: `obj[i1:i2] = b'...'`. Также можно читать и записывать данные, начиная с текущей позиции файла, и перемещаться по файлу с помощью [`seek()`](https://python-all.ru/3.1/library/mmap.html#mmap.seek) в разные позиции.1011Файл, отображаемый в память, создаётся конструктором [`mmap`](https://python-all.ru/3.1/library/mmap.html#mmap.mmap), который различается в Unix и Windows. В любом случае необходимо предоставить файловый дескриптор файла, открытого для обновления. Если нужно отобразить существующий файловый объект Python, используйте его метод `fileno()`, чтобы получить правильное значение параметра *fileno*. В противном случае можно открыть файл с помощью функции [`os.open()`](https://python-all.ru/3.1/library/os.html#os.open), которая возвращает файловый дескриптор напрямую (файл всё равно нужно будет закрыть по завершении).1213Для обеих версий конструктора (Unix и Windows) *access* может быть указан как необязательный именованный параметр. *access* принимает одно из трёх значений: `ACCESS_READ`, `ACCESS_WRITE` или `ACCESS_COPY`, которые задают соответственно память только для чтения, сквозную запись или копирование при записи. *access* можно использовать как в Unix, так и в Windows. Если *access* не указан, Windows mmap возвращает отображение со сквозной записью. Начальные значения памяти для всех трёх типов доступа берутся из указанного файла. Присваивание отображению памяти с `ACCESS_READ` вызывает исключение [`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError). Присваивание отображению памяти с `ACCESS_WRITE` затрагивает как память, так и базовый файл. Присваивание отображению памяти с `ACCESS_COPY` затрагивает память, но не обновляет базовый файл.1415Для отображения анонимной памяти в качестве fileno следует передать -1 вместе с длиной.1617#### `class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset])`1819**(Версия Windows)** Отображает *length* байтов из файла, указанного файловым дескриптором *fileno*, и создаёт объект mmap. Если *length* больше текущего размера файла, файл расширяется до *length* байтов. Если *length* равно `0`, максимальная длина отображения равна текущему размеру файла, за исключением случая, когда файл пуст – тогда Windows вызывает исключение (нельзя создать пустое отображение в Windows).2021*tagname*, если указан и не равен `None`, представляет собой строку, задающую имя тега для отображения. Windows позволяет иметь много разных отображений одного и того же файла. Если указать имя существующего тега, этот тег открывается, в противном случае создаётся новый тег с этим именем. Если этот параметр опущен или равен `None`, отображение создаётся без имени. Отказ от использования параметра tag поможет сохранить переносимость кода между Unix и Windows.2223*offset* может быть задан как неотрицательное целое смещение. Ссылки mmap будут относительными к этому смещению от начала файла. *offset* по умолчанию равен 0. *offset* должен быть кратен ALLOCATIONGRANULARITY.2425#### `class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE|PROT_READ, access=ACCESS_DEFAULT[, offset])`2627**(Версия Unix)** Отображает *length* байт из файла, заданного файловым дескриптором *fileno*, и возвращает объект mmap. Если *length* равен `0`, максимальная длина отображения будет равна текущему размеру файла на момент вызова [`mmap`](https://python-all.ru/3.1/library/mmap.html#mmap.mmap).2829*flags* определяет характер отображения. `MAP_PRIVATE` создаёт частное отображение с копированием при записи, поэтому изменения содержимого объекта mmap будут частными для этого процесса, а `MAP_SHARED` создаёт отображение, которое используется совместно со всеми другими процессами, отображающими те же области файла. Значение по умолчанию – `MAP_SHARED`.3031*prot*, если указан, задаёт желаемую защиту памяти; два наиболее полезных значения – `PROT_READ` и `PROT_WRITE`, которые указывают, что страницы можно читать или записывать. *prot* по умолчанию равен `PROT_READ | PROT_WRITE`.3233*access* может быть указан вместо *flags* и *prot* как необязательный именованный параметр. Указывать одновременно *flags*, *prot* и *access* – ошибка. Информацию о том, как использовать этот параметр, см. в описании *access* выше.3435*offset* может быть задан как неотрицательное целое смещение. Ссылки mmap будут относительными к этому смещению от начала файла. *offset* по умолчанию равен 0. *offset* должен быть кратен PAGESIZE или ALLOCATIONGRANULARITY.3637Для обеспечения корректности созданного отображения в память файл, заданный дескриптором *fileno*, внутренне автоматически синхронизируется с физическим хранилищем на Mac OS X и OpenVMS.3839В этом примере показан простой способ использования [`mmap`](https://python-all.ru/3.1/library/mmap.html#mmap.mmap):4041```python42import mmap4344# записать простой пример файла45with open("hello.txt", "wb") as f:46 f.write(b"Hello Python!\n")4748with open("hello.txt", "r+b") as f:49 # отобразить файл в память, размер 0 означает весь файл50 map = mmap.mmap(f.fileno(), 0)51 # прочитать содержимое с помощью стандартных методов файла52 print(map.readline()) # выводит b"Hello Python!\n"53 # чтение содержимого с помощью срезовой нотации54 print(map[:5]) # выводит b"Hello"55 # обновление содержимого с помощью срезовой нотации;56 # новое содержимое должно быть того же размера57 map[6:] = b" world!\n"58 # ... и снова прочитать стандартными методами файлов59 map.seek(0)60 print(map.readline()) # выводит b"Hello world!\n"61 # закрыть отображение62 map.close()63```6465Следующий пример демонстрирует, как создать анонимное отображение и обмениваться данными между родительским и дочерним процессами:6667```python68import mmap69import os7071map = mmap.mmap(-1, 13)72map.write(b"Hello world!")7374pid = os.fork()7576if pid == 0: # В дочернем процессе77 map.seek(0)78 print(map.readline())7980 map.close()81```8283Объекты файлов с отображением в память поддерживают следующие методы:8485#### `mmap.close()`8687Закрывает файл. Последующие вызовы других методов объекта приведут к возникновению исключения.8889#### `mmap.find(sub[, start[, end]])`9091Возвращает наименьший индекс в объекте, где встречается подпоследовательность9293*sub*9495, при условии, что9697*sub*9899содержится в диапазоне \[100101*start*102103,104105*end*106107\]. Необязательные аргументы108109*start*110111и112113*end*114115интерпретируются как в записи среза. В случае неудачи возвращает116117`-1`118119.120121#### `mmap.flush([offset[, size]])`122123Сбрасывает изменения, внесённые в копию файла в памяти, обратно на диск. Без вызова этого метода нет гарантии, что изменения будут записаны до уничтожения объекта. Если указаны *offset* и *size*, на диск будут сброшены только изменения в заданном диапазоне байтов; в противном случае сбрасывается вся область отображения.124125**(версия Windows)** Ненулевое возвращённое значение означает успех; нулевое – неудачу.126127**(версия Unix)** Возвращается нулевое значение, означающее успех. При ошибке вызова возбуждается исключение.128129#### `mmap.move(dest, src, count)`130131Копирует132133*count*134135байт, начиная со смещения136137*src*138139, в целевой индекс140141*dest*142143. Если mmap был создан с144145`ACCESS_READ`146147, то вызовы move приведут к исключению148149[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)150151.152153#### `mmap.read(num)`154155Возвращает объект156157[`bytes`](https://python-all.ru/3.1/library/functions.html#bytes)158159, содержащий до160161*num*162163байт, начиная с текущей позиции в файле; позиция файла обновляется и указывает на байты, следующие за возвращёнными.164165#### `mmap.read_byte()`166167Возвращает байт в текущей позиции файла в виде целого числа и увеличивает позицию файла на 1.168169#### `mmap.readline()`170171Возвращает одну строку, начиная с текущей позиции в файле и до следующего символа новой строки.172173#### `mmap.resize(newsize)`174175Изменяет размер отображения и базового файла (если он есть). Если mmap был создан с176177`ACCESS_READ`178179или180181`ACCESS_COPY`182183, изменение размера вызовет исключение184185[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)186187.188189#### `mmap.rfind(sub[, start[, end]])`190191Возвращает наибольший индекс в объекте, где найдена подпоследовательность192193*sub*194195, такой, что196197*sub*198199содержится в диапазоне \[200201*start*202203,204205*end*206207\]. Необязательные аргументы208209*start*210211и212213*end*214215интерпретируются как в нотации среза. Возвращает216217`-1`218219при неудаче.220221#### `mmap.seek(pos[, whence])`222223Устанавливает текущую позицию файла. Аргумент224225*whence*226227является необязательным и по умолчанию равен228229`os.SEEK_SET`230231или232233`0`234235(абсолютное позиционирование); другие значения:236237`os.SEEK_CUR`238239или240241`1`242243(смещение относительно текущей позиции) и244245`os.SEEK_END`246247или248249`2`250251(смещение относительно конца файла).252253#### `mmap.size()`254255Возвращает длину файла, которая может быть больше размера области отображения памяти.256257#### `mmap.tell()`258259Возвращает текущую позицию файлового указателя.260261#### `mmap.write(bytes)`262263Записывает байты из264265*bytes*266267в память в текущей позиции файлового указателя; позиция файла обновляется так, чтобы указывать после записанных байтов. Если mmap был создан с268269`ACCESS_READ`270271, то запись в него вызовет исключение272273[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)274275.276277#### `mmap.write_byte(byte)`278279Записывает целое число280281*byte*282283в память в текущую позицию файлового указателя; позиция файла увеличивается на284285`1`286287. Если mmap был создан с288289`ACCESS_READ`290291, то запись вызовет исключение292293[`TypeError`](https://python-all.ru/3.1/library/exceptions.html#TypeError)294295.296