mmap.md
1> **Источник:** https://python-all.ru/3.0/library/mmap.html2>3> «Документация Python на русском» – неофициальный перевод официальной документации Python: версии от 2.6 до 3.16, полнотекстовый поиск, английский оригинал рядом с переводом. Эта Markdown-версия страницы предназначена для работы с LLM: вставьте её в ChatGPT, Claude или Cursor.45---67# `mmap` – поддержка файлов, отображаемых в память89Объекты файлов, отображаемых в память, ведут себя и как строки, и как файловые объекты. Однако, в отличие от обычных строковых объектов, они являются изменяемыми. Объекты mmap можно использовать в большинстве мест, где ожидаются строки; например, можно использовать модуль [`re`](https://python-all.ru/3.0/library/re.html#module-re) для поиска по файлу, отображённому в память. Поскольку они изменяемы, можно изменить один символ, выполнив `obj[index] = 'a'`, или изменить подстроку, присвоив срезу: `obj[i1:i2] = '...'`. Также можно читать и записывать данные, начиная с текущей позиции файла, и [`seek()`](https://python-all.ru/3.0/library/mmap.html#mmap.seek) перемещаться по файлу в разные позиции.1011Файл, отображаемый в память, создаётся конструктором [`mmap`](https://python-all.ru/3.0/library/mmap.html#mmap.mmap), который различается в Unix и Windows. В любом случае необходимо предоставить файловый дескриптор файла, открытого для обновления. Если нужно отобразить существующий файловый объект Python, используйте его метод `fileno()`, чтобы получить правильное значение параметра *fileno*. В противном случае можно открыть файл с помощью функции [`os.open()`](https://python-all.ru/3.0/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.0/library/exceptions.html#exceptions.TypeError). Присваивание отображению памяти с `ACCESS_WRITE` затрагивает как память, так и базовый файл. Присваивание отображению памяти с `ACCESS_COPY` затрагивает память, но не обновляет базовый файл.1415Для отображения анонимной памяти в качестве fileno следует передать -1 вместе с длиной.1617#### `[mmap.mmap]class mmap.mmap(fileno, length[, tagname[, access[, 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[, prot[, access[, offset]]]])`2627**(Версия Unix)** Отображает *length* байт из файла, заданного файловым дескриптором *fileno*, и возвращает объект mmap. Если *length* равен `0`, максимальная длина отображения будет равна текущему размеру файла на момент вызова [`mmap`](https://python-all.ru/3.0/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В этом примере показан простой способ использования [`mmap`](https://python-all.ru/3.0/library/mmap.html#mmap.mmap):3839```python40import mmap4142# записать простой пример файла43with open("hello.txt", "w") as f:44 f.write("Hello Python!\n")4546with open("hello.txt", "r+") as f:47 # отобразить файл в память, размер 0 означает весь файл48 map = mmap.mmap(f.fileno(), 0)49 # прочитать содержимое с помощью стандартных методов файла50 print(map.readline()) # выводит "Hello Python!"51 # чтение содержимого с помощью срезовой нотации52 print(map[:5]) # выводит "Hello"53 # обновление содержимого с помощью срезовой нотации;54 # новое содержимое должно быть того же размера55 map[6:] = " world!\n"56 # ... и снова прочитать стандартными методами файлов57 map.seek(0)58 print(map.readline()) # выводит "Hello world!"59 # закрыть отображение60 map.close()61```6263Следующий пример демонстрирует, как создать анонимное отображение и обмениваться данными между родительским и дочерним процессами:6465```python66import mmap67import os6869map = mmap.mmap(-1, 13)70map.write("Hello world!")7172pid = os.fork()7374if pid == 0: # В дочернем процессе75 map.seek(0)76 print(map.readline())7778 map.close()79```8081Объекты файлов с отображением в память поддерживают следующие методы:8283#### `[mmap.close]mmap.close()`8485Закрывает файл. Последующие вызовы других методов объекта приведут к возникновению исключения.8687#### `[mmap.find]mmap.find(string[, start[, end]])`8889Возвращает наименьший индекс в объекте, где подстрока9091*string*9293найдена, такой, что9495*string*9697содержится в диапазоне \[9899*start*100101,102103*end*104105\]. Необязательные аргументы106107*start*108109и110111*end*112113интерпретируются как в нотации срезов. Возвращает114115`-1`116117в случае неудачи.118119#### `[mmap.flush]mmap.flush([offset, size])`120121Сбрасывает изменения, внесённые в копию файла в памяти, обратно на диск. Без вызова этого метода нет гарантии, что изменения будут записаны до уничтожения объекта. Если указаны *offset* и *size*, на диск будут сброшены только изменения в заданном диапазоне байтов; в противном случае сбрасывается вся область отображения.122123**(версия Windows)** Ненулевое возвращённое значение означает успех; нулевое – неудачу.124125**(версия Unix)** Возвращается нулевое значение, означающее успех. При ошибке вызова возбуждается исключение.126127#### `[mmap.move]mmap.move(dest, src, count)`128129Копирует130131*count*132133байт, начиная с смещения134135*src*136137, в целевой индекс138139*dest*140141. Если mmap был создан с142143`ACCESS_READ`144145, то вызовы move будут вызывать исключение146147[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)148149.150151#### `[mmap.read]mmap.read(num)`152153Возвращает строку, содержащую до154155*num*156157байт, начиная с текущей позиции файла; позиция файла обновляется так, чтобы указывать за байтами, которые были возвращены.158159#### `[mmap.read_byte]mmap.read_byte()`160161Возвращает строку длиной 1, содержащую символ на текущей позиции файла, и увеличивает позицию файла на 1.162163#### `[mmap.readline]mmap.readline()`164165Возвращает одну строку, начиная с текущей позиции в файле и до следующего символа новой строки.166167#### `[mmap.resize]mmap.resize(newsize)`168169Изменяет размер отображения и, если есть, нижележащего файла. Если mmap был создан с170171`ACCESS_READ`172173или174175`ACCESS_COPY`176177, изменение размера отображения вызовет исключение178179[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)180181.182183#### `[mmap.rfind]mmap.rfind(string[, start[, end]])`184185Возвращает наибольший индекс в объекте, где подстрока186187*string*188189найдена, такой, что190191*string*192193содержится в диапазоне \[194195*start*196197,198199*end*200201\]. Необязательные аргументы202203*start*204205и206207*end*208209интерпретируются как в нотации срезов. Возвращает210211`-1`212213в случае неудачи.214215#### `[mmap.seek]mmap.seek(pos[, whence])`216217Устанавливает текущую позицию файла. Аргумент218219*whence*220221является необязательным и по умолчанию равен222223`os.SEEK_SET`224225или226227`0`228229(абсолютное позиционирование); другие значения:230231`os.SEEK_CUR`232233или234235`1`236237(смещение относительно текущей позиции) и238239`os.SEEK_END`240241или242243`2`244245(смещение относительно конца файла).246247#### `[mmap.size]mmap.size()`248249Возвращает длину файла, которая может быть больше размера области отображения памяти.250251#### `[mmap.tell]mmap.tell()`252253Возвращает текущую позицию файлового указателя.254255#### `[mmap.write]mmap.write(string)`256257Записывает байты из258259*string*260261в память на текущей позиции файлового указателя; позиция файла обновляется так, чтобы указывать за записанными байтами. Если mmap был создан с262263`ACCESS_READ`264265, то запись в него вызовет исключение266267[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)268269.270271#### `[mmap.write_byte]mmap.write_byte(byte)`272273Записывает строку из одного символа274275*byte*276277в память на текущей позиции файлового указателя; позиция файла увеличивается на278279`1`280281. Если mmap был создан с282283`ACCESS_READ`284285, то запись в него вызовет исключение286287[`TypeError`](https://python-all.ru/3.0/library/exceptions.html#exceptions.TypeError)288289.290