mmap-поддержка файлов с сопоставленной памятью
Этот модуль не работает или недоступен на платформах WebAssembly wasm32-emscripten и wasm32-wasi . Дополнительную информацию см. в разделе Платформы WebAssembly .
Отображенные в память файловые объекты ведут себя и как bytearray , и как файловые объекты . Вы можете использовать объекты mmap в большинстве мест, где ожидается использование bytearray ; например, вы можете использовать модуль re для поиска в отображенном в памяти файле. Вы также можете изменить один байт, выполнив obj[index] = 97 , или изменить подпоследовательность, назначив слайсу: obj[i1:i2] = b’. ‘ . Вы также можете читать и записывать данные, начиная с текущей позиции файла, и seek() через файл в разные позиции.
Файл с отображением памяти создается конструктором mmap , который отличается в Unix и Windows. В любом случае вы должны указать файловый дескриптор для файла, открытого для обновления. Если вы хотите отобразить существующий файловый объект Python, используйте его fileno() , чтобы получить правильное значение для параметра fileno . В противном случае вы можете открыть файл с помощью функции os.open() , которая напрямую возвращает дескриптор файла (по завершении файл все равно должен быть закрыт).
Если вы хотите создать отображение памяти для буферизованного файла с возможностью записи, вы должны сначала flush() файл. Это необходимо, чтобы гарантировать, что локальные модификации буферов действительно доступны для отображения.
Для версий конструктора как для Unix, так и для Windows доступ может быть указан как необязательный параметр ключевого слова. доступа принимает один из четырех значений: ACCESS_READ , ACCESS_WRITE или ACCESS_COPY указать только для чтения, записи или с помощью копирования на записи памяти соответственно, или ACCESS_DEFAULT отложить до прот . доступ можно использовать как в Unix, так и в Windows. Если доступ не указан, Windows mmap возвращает отображение со сквозной записью. Начальные значения памяти для всех трех типов доступа берутся из указанного файла. Присвоение карте памяти ACCESS_READ вызывает TypeError исключение. Назначение карте памяти ACCESS_WRITE влияет как на память, так и на базовый файл. Назначение карте памяти ACCESS_COPY влияет на память, но не обновляет базовый файл.
Изменено в версии 3.7: Добавлена константа ACCESS_DEFAULT .
Для отображения анонимной памяти вместе с длиной необходимо передать в качестве фильтра -1.
class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT[, offset])
(Версия для Windows) Карта длина байты из файла , указанного в файл ручка fileno , и создает объект MMAP. Если длина больше текущего размера файла, файл расширяется, чтобы содержать байты длины . Если длина равна 0 , максимальная длина карты является текущим размером файла, за исключением того, что если файл пуст, Windows вызывает исключение (вы не можете создать пустое сопоставление в Windows).
tagname , если он указан, а не None , представляет собой строку, дающую имя тега для отображения. Windows позволяет вам иметь много разных сопоставлений с одним и тем же файлом. Если вы указываете имя существующего тега, этот тег открывается, в противном случае создается новый тег с этим именем. Если этот параметр опущен или None , сопоставление создается без имени. Отказ от использования параметра tag поможет сохранить ваш код переносимым между Unix и Windows.
смещение может быть указано как неотрицательное целое смещение. Ссылки mmap будут относиться к смещению от начала файла. смещение по умолчанию равно 0. смещение должно быть кратным ALLOCATIONGRANULARITY .
Поднимает аудита событий mmap.__new__ с аргументами fileno , length , access , offset .
class mmap.mmap( fileno , длина , flags=MAP_SHARED , prot=PROT_WRITE|PROT_READ , access=ACCESS_DEFAULT [, offset ])
(Unix — версия) Карты длина байты из файла , указанного дескриптора файла fileno , и возвращает объект MMAP. Если длина равна 0 , максимальная длина карты будет текущим размером файла при вызове mmap .
flags указывает характер отображения. MAP_PRIVATE создает частное сопоставление с копированием при записи, поэтому изменения содержимого объекта mmap будут частными для этого процесса, а MAP_SHARED создает сопоставление, совместно используемое всеми другими процессами, отображающими те же области файла. Значение по умолчанию — MAP_SHARED . Некоторые системы имеют дополнительные возможные флаги с полным списком, указанным в константах MAP_* .
prot , если он указан, дает желаемую защиту памяти; два наиболее полезных значения — PROT_READ и PROT_WRITE , чтобы указать, что страницы могут быть прочитаны или записаны. prot по умолчанию PROT_READ | PROT_WRITE .
Доступ может быть указан вместо flags и prot как необязательный параметр ключевого слова. Ошибочно указывать и флаги , и защиту, и доступ . См. Описание доступа выше для получения информации о том, как использовать этот параметр.
смещение может быть указано как неотрицательное целое смещение. Ссылки mmap будут относиться к смещению от начала файла. смещение по умолчанию равно 0. смещение должно быть кратным ALLOCATIONGRANULARITY , что равно PAGESIZE в системах Unix.
Чтобы обеспечить достоверность созданного сопоставления памяти, файл, указанный дескриптором fileno , автоматически синхронизируется внутри с физическим резервным хранилищем в macOS.
В этом примере показан простой способ использования mmap :
import mmap # напишите простой пример файла with open("hello.txt", "wb") as f: f.write(b"Hello Python!\n") with open("hello.txt", "r+b") as f: # memory-map файл, размер 0 означает весь файл mm = mmap.mmap(f.fileno(), 0) # читать содержимое стандартными файловыми методами print(mm.readline()) # выводит b "Hello Python! \ n" # читать контент через нотацию среза print(mm[:5]) # выводит b "Привет" # обновить содержимое, используя нотацию фрагментов; # обратите внимание, что новый контент должен иметь такой же размер mm[6:] = b" world!\n" # . и прочитайте снова, используя стандартные файловые методы mm.seek(0) print(mm.readline()) # выводит b "Hello world! \ n" # закрыть карту 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: # В дочернем процессе mm.seek(0) print(mm.readline()) mm.close()
Поднимает аудита событий mmap.__new__ с аргументами fileno , length , access , offset .
Файловые объекты,отображенные на карте памяти,поддерживают следующие методы:
Закрывает карту.Последующие вызовы других методов объекта приводят к возникновению исключения ValueError.Это не закроет открытый файл.
Возвращает самый низкий индекс в объекте , где подпоследовательность суб найден, таким образом, что к югу содержатся в диапазоне [ начать , конец ]. Необязательные аргументы start и end интерпретируются как в нотации среза. Возвращает -1 в случае неудачи.
Изменено в версии 3.5: теперь принимается записываемый байтовый объект .
Сбрасывает изменения, внесенные в копию файла в памяти, обратно на диск. Без использования этого вызова нет гарантии, что изменения будут записаны до того, как объект будет уничтожен. Если указаны смещение и размер , на диск будут сброшены только изменения в заданном диапазоне байтов; в противном случае сбрасывается весь экстент отображения. смещение должно быть кратно PAGESIZE или ALLOCATIONGRANULARITY .
None успеха ничего не возвращается. При сбое вызова возникает исключение.
Изменено в версии 3.8:Ранее при успешной работе возвращалось ненулевое значение;при ошибке в Windows возвращался ноль.Нулевое значение возвращалось при успешном выполнении;исключение возвращалось при ошибке под Unix.
Отправить ядру опцию совета относительно области памяти, начинающейся с начала и увеличивающей длину в байтах. Опция должна быть одна из MADV_ * констант , доступных в системе. Если начало и длина опущены, отображается все отображение. В некоторых системах (включая Linux) начало должно быть кратно PAGESIZE .
Доступность: Системы с системным вызовом madvise() .
Скопируйте счетные байты, начиная со смещения src, в целевой индекс dest . Если mmap был создан с помощью ACCESS_READ , то вызовы move TypeError исключение TypeError .
Возвращает bytes , содержащие до n байтов, начиная с текущей позиции в файле. Если аргумент опущен, None или отрицательный, возвращаются все байты от текущей позиции файла до конца сопоставления. Позиция в файле обновляется так, чтобы она указывала после возвращенных байтов.
Изменено в версии 3.3: Аргумент можно опустить или None .
Возвращает байт на текущую позицию файла в виде целого числа и продвигает позицию файла на 1.
Возвращает одну строку,начиная с текущей позиции файла и до следующей новой строки.Позиция файла обновляется,чтобы указывать после байтов,которые были возвращены.
Изменяет размер карты и базового файла, если таковой имеется. Если mmap был создан с ACCESS_READ или ACCESS_COPY , изменение размера карты вызовет исключение TypeError .
В Windows : изменение размера карты вызовет OSError , если есть другие карты для файла с таким же именем. Изменение размера анонимной карты (т.е. по сравнению с файлом подкачки) автоматически создаст новую карту с исходными данными, скопированными до длины нового размера.
Изменения в версии 3.11:Корректно не работает при попытке изменить размер,когда удерживается другая карта Позволяет изменять размер по анонимной карте в Windows
Возвращает самый высокий показатель в объекте , где подпоследовательность суб найден, таким образом, что к югу содержатся в диапазоне [ начать , конец ]. Необязательные аргументы start и end интерпретируются как в нотации среза. Возвращает -1 в случае неудачи.
Изменено в версии 3.5: теперь принимается записываемый байтовый объект .
Установите текущую позицию файла. os.SEEK_SET необязателен и по умолчанию равен os.SEEK_SET или 0 (абсолютное позиционирование файла); другими значениями являются os.SEEK_CUR или 1 (поиск относительно текущей позиции) и os.SEEK_END или 2 (поиск относительно конца файла).
Возвращает длину файла,которая может быть больше,чем размер области отображения памяти.
Возвращает текущую позицию указателя на файл.
Записать байты в байтах в память в текущей позиции указателя файла и вернуть количество записанных байтов (никогда не меньше len(bytes) , поскольку в случае сбоя записи возникает ValueError ). Положение файла обновляется до точки после записанных байтов. Если mmap был создан с ACCESS_READ , то запись в него вызовет исключение TypeError .
Изменено в версии 3.5: теперь принимается записываемый байтовый объект .
Изменено в версии 3.6:Теперь возвращается количество записанных байтов.
Записать целочисленный байт в память в текущей позиции указателя файла; позиция файла увеличивается на 1 . Если mmap был создан с ACCESS_READ , то запись в него вызовет исключение TypeError .
MADV_* Constants
mmap.MADV_NORMAL mmap.MADV_RANDOM mmap.MADV_SEQUENTIAL mmap.MADV_WILLNEED mmap.MADV_DONTNEED mmap.MADV_REMOVE mmap.MADV_DONTFORK mmap.MADV_DOFORK mmap.MADV_HWPOISON mmap.MADV_MERGEABLE mmap.MADV_UNMERGEABLE mmap.MADV_SOFT_OFFLINE mmap.MADV_HUGEPAGE mmap.MADV_NOHUGEPAGE mmap.MADV_DONTDUMP mmap.MADV_DODUMP mmap.MADV_FREE mmap.MADV_NOSYNC mmap.MADV_AUTOSYNC mmap.MADV_NOCORE mmap.MADV_CORE mmap.MADV_PROTECT mmap.MADV_FREE_REUSABLE mmap.MADV_FREE_REUSE
Эти параметры можно передать в mmap.madvise() . Не все варианты будут присутствовать в каждой системе.
Наличие:Системы с системным вызовом madvise().
MAP_* Constants
mmap.MAP_SHARED mmap.MAP_PRIVATE mmap.MAP_DENYWRITE mmap.MAP_EXECUTABLE mmap.MAP_ANON mmap.MAP_ANONYMOUS mmap.MAP_POPULATE mmap.MAP_STACK
Это различные флаги, которые можно передать в mmap.mmap() . Обратите внимание, что некоторые параметры могут отсутствовать в некоторых системах.
Изменения в версии 3.10:Добавлена константа MAP_POPULATE.
Новое в версии 3.11:Добавлена константа MAP_STACK.
Python 3.11
Исходный код:Lib/mimetypes.py Модуль mimetypes конвертирует между именем файла или URL и связанным с ним расширением.
Модули,описанные в этой главе,реализуют различные интерфейсы алгоритмов,которые в основном полезны для мультимедийных приложений.
Исходный код:Lib/modulefinder.py Этот модуль предоставляет класс ModuleFinder,который может быть использован для определения набора модулей,импортируемых скриптом.
Модули,описанные в этой главе,предоставляют новые способы импорта других Python и крючки для настройки процесса.