mmap — Unterstützung für speicherabgebildete Dateien

Verfügbarkeit: nicht WASI.

Dieses Modul funktioniert nicht oder ist nicht auf WebAssembly verfügbar. Weitere Informationen finden Sie unter WebAssembly-Plattformen.

Speicherabgebildete Datei-Objekte verhalten sich sowohl wie bytearray als auch wie Datei-Objekte. Sie können mmap-Objekte an den meisten Stellen verwenden, wo bytearray erwartet wird; zum Beispiel können Sie das Modul re verwenden, um eine speicherabgebildete Datei zu durchsuchen. Sie können auch ein einzelnes Byte ändern, indem Sie obj[index] = 97 verwenden, oder eine Teilsequenz ändern, indem Sie einer Slice zuweisen: obj[i1:i2] = b'...'. Sie können auch Daten ab der aktuellen Dateiposition lesen und schreiben und mit seek() zu verschiedenen Positionen im Datei springen.

Eine speicherabgebildete Datei wird durch den Konstruktor mmap erstellt, der sich unter Unix und unter Windows unterscheidet. In beiden Fällen müssen Sie einen Dateideskriptor für eine zum Aktualisieren geöffnete Datei angeben. Wenn Sie ein vorhandenes Python-Datei-Objekt abbilden möchten, verwenden Sie dessen Methode fileno(), um den korrekten Wert für den Parameter fileno zu erhalten. Andernfalls können Sie die Datei mit der Funktion os.open() öffnen, die direkt einen Dateideskriptor zurückgibt (die Datei muss danach noch geschlossen werden).

Hinweis

Wenn Sie eine Speicherabbildung für eine schreibbare, gepufferte Datei erstellen möchten, sollten Sie die Datei zuerst flush(). Dies ist notwendig, um sicherzustellen, dass lokale Modifikationen der Puffer tatsächlich für die Abbildung verfügbar sind.

Sowohl für die Unix- als auch für die Windows-Version des Konstruktors kann access als optionaler Schlüsselwortparameter angegeben werden. access akzeptiert einen von vier Werten: ACCESS_READ, ACCESS_WRITE oder ACCESS_COPY, um schreibgeschützte, Write-Through- oder Copy-on-Write-Speicher anzugeben, oder ACCESS_DEFAULT, um auf prot zurückzugreifen. access kann sowohl unter Unix als auch unter Windows verwendet werden. Wenn access nicht angegeben ist, gibt Windows mmap eine Write-Through-Abbildung zurück. Die anfänglichen Speicherwerte für alle drei Zugriffstypen werden aus der angegebenen Datei übernommen. Die Zuweisung zu einer ACCESS_READ-Speicherabbildung löst eine TypeError-Ausnahme aus. Die Zuweisung zu einer ACCESS_WRITE-Speicherabbildung wirkt sich sowohl auf den Speicher als auch auf die zugrunde liegende Datei aus. Die Zuweisung zu einer ACCESS_COPY-Speicherabbildung wirkt sich auf den Speicher aus, aktualisiert aber nicht die zugrunde liegende Datei.

Geändert in Version 3.7: Konstante ACCESS_DEFAULT hinzugefügt.

Um anonymen Speicher abzubilden, sollte -1 zusammen mit der Länge als fileno übergeben werden.

class mmap.mmap(fileno, length, tagname=None, access=ACCESS_DEFAULT, offset=0)

(Windows-Version) Bildet length Bytes aus der Datei ab, die durch den Dateihandle fileno angegeben wird, und erstellt ein mmap-Objekt. Wenn length größer als die aktuelle Größe der Datei ist, wird die Datei erweitert, um length Bytes zu enthalten. Wenn length 0 ist, ist die maximale Länge der Abbildung die aktuelle Größe der Datei, außer dass unter Windows eine Ausnahme ausgelöst wird, wenn die Datei leer ist (Sie können unter Windows keine leere Abbildung erstellen).

tagname, falls angegeben und nicht None, ist ein String, der einen Tag-Namen für die Abbildung angibt. Windows erlaubt es Ihnen, viele verschiedene Abbildungen auf dieselbe Datei zu haben. Wenn Sie den Namen eines vorhandenen Tags angeben, wird dieser Tag geöffnet, andernfalls wird ein neuer Tag mit diesem Namen erstellt. Wenn dieser Parameter weggelassen wird oder None ist, wird die Abbildung ohne Namen erstellt. Die Vermeidung der Verwendung des Parameters tagname trägt zur Portabilität Ihres Codes zwischen Unix und Windows bei.

offset kann als nicht-negativer Integer-Offset angegeben werden. mmap-Referenzen beziehen sich relativ zum Offset vom Anfang der Datei. offset hat den Standardwert 0. offset muss ein Vielfaches der ALLOCATIONGRANULARITY sein.

Löst ein Audit-Ereignis mmap.__new__ mit den Argumenten fileno, length, access, offset aus.

class mmap.mmap(fileno, length, flags=MAP_SHARED, prot=PROT_WRITE | PROT_READ, access=ACCESS_DEFAULT, offset=0, *, trackfd=True)

(Unix-Version) Bildet length Bytes aus der Datei ab, die durch den Dateideskriptor fileno angegeben wird, und gibt ein mmap-Objekt zurück. Wenn length 0 ist, ist die maximale Länge der Abbildung die aktuelle Größe der Datei, wenn mmap aufgerufen wird.

flags gibt die Art der Abbildung an. MAP_PRIVATE erstellt eine private Copy-on-Write-Abbildung, sodass Änderungen am Inhalt des mmap-Objekts nur für diesen Prozess gelten, und MAP_SHARED erstellt eine Abbildung, die mit allen anderen Prozessen, die dieselben Bereiche der Datei abbilden, gemeinsam genutzt wird. Der Standardwert ist MAP_SHARED. Einige Systeme haben zusätzliche mögliche Flags, die vollständige Liste ist in den MAP_* Konstanten aufgeführt.

prot, falls angegeben, gibt den gewünschten Speicherschutz an; die beiden nützlichsten Werte sind PROT_READ und PROT_WRITE, um anzugeben, dass die Seiten gelesen oder geschrieben werden können. prot hat den Standardwert PROT_READ | PROT_WRITE.

access kann anstelle von flags und prot als optionaler Schlüsselwortparameter angegeben werden. Es ist ein Fehler, sowohl flags, prot als auch access anzugeben. Siehe die Beschreibung von access oben für Informationen zur Verwendung dieses Parameters.

offset kann als nicht-negativer Integer-Offset angegeben werden. mmap-Referenzen beziehen sich relativ zum Offset vom Anfang der Datei. offset hat den Standardwert 0. offset muss ein Vielfaches von ALLOCATIONGRANULARITY sein, was unter Unix-Systemen PAGESIZE entspricht.

Wenn trackfd False ist, wird der durch fileno angegebene Dateideskriptor nicht dupliziert und das resultierende mmap-Objekt wird nicht mit der zugrunde liegenden Datei der Abbildung verknüpft. Das bedeutet, dass die Methoden size() und resize() fehlschlagen. Dieser Modus ist nützlich, um die Anzahl offener Dateideskriptoren zu begrenzen.

Um die Gültigkeit der erstellten Speicherabbildung zu gewährleisten, wird die durch den Deskriptor fileno angegebene Datei unter macOS intern automatisch mit dem physischen Backing Store synchronisiert.

Geändert in Version 3.13: Der Parameter trackfd wurde hinzugefügt.

Dieses Beispiel zeigt eine einfache Möglichkeit, mmap zu verwenden

import mmap

# write a simple example file
with open("hello.txt", "wb") as f:
    f.write(b"Hello Python!\n")

with open("hello.txt", "r+b") as f:
    # memory-map the file, size 0 means whole file
    mm = mmap.mmap(f.fileno(), 0)
    # read content via standard file methods
    print(mm.readline())  # prints b"Hello Python!\n"
    # read content via slice notation
    print(mm[:5])  # prints b"Hello"
    # update content using slice notation;
    # note that new content must have same size
    mm[6:] = b" world!\n"
    # ... and read again using standard file methods
    mm.seek(0)
    print(mm.readline())  # prints b"Hello  world!\n"
    # close the map
    mm.close()

mmap kann auch als Kontextmanager in einer with-Anweisung verwendet werden

import mmap

with mmap.mmap(-1, 13) as mm:
    mm.write(b"Hello world!")

Hinzugefügt in Version 3.2: Unterstützung für Kontextmanager.

Das nächste Beispiel demonstriert, wie eine anonyme Abbildung erstellt und Daten zwischen Eltern- und Kindprozessen ausgetauscht werden

import mmap
import os

mm = mmap.mmap(-1, 13)
mm.write(b"Hello world!")

pid = os.fork()

if pid == 0:  # In a child process
    mm.seek(0)
    print(mm.readline())

    mm.close()

Löst ein Audit-Ereignis mmap.__new__ mit den Argumenten fileno, length, access, offset aus.

Speicherabgebildete Datei-Objekte unterstützen die folgenden Methoden

close()

Schließt die mmap. Nachfolgende Aufrufe anderer Methoden des Objekts führen zu einer ValueError-Ausnahme. Dies schließt die geöffnete Datei nicht.

closed

Wenn die Datei geschlossen ist, ist dies True.

Hinzugefügt in Version 3.2.

find(sub[, start[, end]])

Gibt den niedrigsten Index im Objekt zurück, an dem die Teilsequenz sub gefunden wird, sodass sub im Bereich [start, end] enthalten ist. Optionale Argumente start und end werden wie in der Slice-Notation interpretiert. Gibt im Fehlerfall -1 zurück.

Geändert in Version 3.5: Schreibbare Bytes-ähnliche Objekte werden jetzt akzeptiert.

flush()
flush(offset, size, /)

Schreibt Änderungen, die an der In-Memory-Kopie einer Datei vorgenommen wurden, zurück auf die Festplatte. Ohne die Verwendung dieses Aufrufs gibt es keine Garantie, dass Änderungen zurückgeschrieben werden, bevor das Objekt zerstört wird. Wenn offset und size angegeben sind, werden nur Änderungen an dem angegebenen Bytebereich auf die Festplatte geschrieben; andernfalls wird der gesamte Bereich der Abbildung geleert. offset muss ein Vielfaches der PAGESIZE oder ALLOCATIONGRANULARITY sein.

Gibt None zurück, um Erfolg anzuzeigen. Eine Ausnahme wird ausgelöst, wenn der Aufruf fehlschlägt.

Geändert in Version 3.8: Zuvor wurde unter Windows ein von Null verschiedener Wert bei Erfolg zurückgegeben; null wurde bei Fehler zurückgegeben. Unter Unix wurde bei Erfolg null zurückgegeben; bei Fehler wurde eine Ausnahme ausgelöst.

madvise(option[, start[, length]])

Sendet den Rat option an den Kernel bezüglich des Speicherbereichs, der bei start beginnt und length Bytes umfasst. option muss eine der auf dem System verfügbaren MADV_* Konstanten sein. Wenn start und length weggelassen werden, wird die gesamte Abbildung abgedeckt. Auf einigen Systemen (einschließlich Linux) muss start ein Vielfaches der PAGESIZE sein.

Verfügbarkeit: Systeme mit dem madvise() Systemaufruf.

Hinzugefügt in Version 3.8.

move(dest, src, count)

Kopiert die count Bytes, beginnend am Offset src, zum Zielindex dest. Wenn die mmap mit ACCESS_READ erstellt wurde, lösen Aufrufe von move eine TypeError-Ausnahme aus.

read([n])

Gibt eine bytes zurück, die bis zu n Bytes ab der aktuellen Dateiposition enthält. Wenn das Argument weggelassen wird, None oder negativ ist, werden alle Bytes von der aktuellen Dateiposition bis zum Ende der Abbildung zurückgegeben. Die Dateiposition wird so aktualisiert, dass sie auf die zurückgegebenen Bytes folgt.

Geändert in Version 3.3: Das Argument kann weggelassen oder None sein.

read_byte()

Gibt ein Byte an der aktuellen Dateiposition als Ganzzahl zurück und verschiebt die Dateiposition um 1.

readline()

Gibt eine einzelne Zeile zurück, beginnend an der aktuellen Dateiposition und bis zum nächsten Zeilenumbruch. Die Dateiposition wird so aktualisiert, dass sie auf die zurückgegebenen Bytes folgt.

resize(newsize)

Ändert die Größe der Abbildung und der zugrunde liegenden Datei, falls vorhanden.

Das Ändern der Größe einer mit access von ACCESS_READ oder ACCESS_COPY erstellten Abbildung löst eine TypeError-Ausnahme aus. Das Ändern der Größe einer mit trackfd auf False gesetzten Abbildung löst eine ValueError-Ausnahme aus.

Unter Windows: Das Ändern der Größe der Abbildung löst eine OSError aus, wenn andere Abbildungen für dieselbe benannte Datei vorhanden sind. Das Ändern der Größe einer anonymen Abbildung (d. h. gegen die Auslagerungsdatei) erstellt stillschweigend eine neue Abbildung mit den ursprünglichen Daten, die bis zur Länge der neuen Größe kopiert werden.

Geändert in Version 3.11: Schlägt korrekt fehl, wenn versucht wird, die Größe zu ändern, wenn eine andere Abbildung gehalten wird. Ermöglicht die Größenänderung gegenüber einer anonymen Abbildung unter Windows.

rfind(sub[, start[, end]])

Gibt den höchsten Index im Objekt zurück, an dem die Teilsequenz sub gefunden wird, sodass sub im Bereich [start, end] enthalten ist. Optionale Argumente start und end werden wie in der Slice-Notation interpretiert. Gibt im Fehlerfall -1 zurück.

Geändert in Version 3.5: Schreibbare Bytes-ähnliche Objekte werden jetzt akzeptiert.

seek(pos[, whence])

Setzt die aktuelle Position der Datei. Das Argument whence ist optional und hat den Standardwert os.SEEK_SET oder 0 (absolute Dateipositionierung); andere Werte sind os.SEEK_CUR oder 1 (relativ zur aktuellen Position suchen) und os.SEEK_END oder 2 (relativ zum Ende der Datei suchen).

Geändert in Version 3.13: Gibt die neue absolute Position zurück anstelle von None.

seekable()

Gibt zurück, ob die Datei das Suchen unterstützt, und der Rückgabewert ist immer True.

Hinzugefügt in Version 3.13.

size()

Gibt die Länge der Datei zurück, die größer sein kann als die Größe des speicherabgebildeten Bereichs.

tell()

Gibt die aktuelle Position des Dateizeigers zurück.

write(bytes)

Schreibt die Bytes in bytes an der aktuellen Position des Dateizeigers in den Speicher und gibt die Anzahl der geschriebenen Bytes zurück (nie weniger als len(bytes), da bei einem Fehler beim Schreiben eine ValueError ausgelöst wird). Die Dateiposition wird so aktualisiert, dass sie auf die geschriebenen Bytes folgt. Wenn die mmap mit ACCESS_READ erstellt wurde, löst das Schreiben eine TypeError-Ausnahme aus.

Geändert in Version 3.5: Schreibbare Bytes-ähnliche Objekte werden jetzt akzeptiert.

Geändert in Version 3.6: Die Anzahl der geschriebenen Bytes wird jetzt zurückgegeben.

write_byte(byte)

Schreibt die Ganzzahl byte an der aktuellen Position des Dateizeigers in den Speicher; die Dateiposition wird um 1 erhöht. Wenn die mmap mit ACCESS_READ erstellt wurde, löst das Schreiben eine TypeError-Ausnahme aus.

MADV_* Konstanten

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

Diese Optionen können an mmap.madvise() übergeben werden. Nicht jede Option ist auf jedem System vorhanden.

Verfügbarkeit: Systeme mit dem madvise()-Systemaufruf.

Hinzugefügt in Version 3.8.

MAP_* Konstanten

mmap.MAP_SHARED
mmap.MAP_PRIVATE
mmap.MAP_32BIT
mmap.MAP_ALIGNED_SUPER
mmap.MAP_ANON
mmap.MAP_ANONYMOUS
mmap.MAP_CONCEAL
mmap.MAP_DENYWRITE
mmap.MAP_EXECUTABLE
mmap.MAP_HASSEMAPHORE
mmap.MAP_JIT
mmap.MAP_NOCACHE
mmap.MAP_NOEXTEND
mmap.MAP_NORESERVE
mmap.MAP_POPULATE
mmap.MAP_RESILIENT_CODESIGN
mmap.MAP_RESILIENT_MEDIA
mmap.MAP_STACK
mmap.MAP_TPRO
mmap.MAP_TRANSLATED_ALLOW_EXECUTE
mmap.MAP_UNIX03

Dies sind die verschiedenen Flags, die an mmap.mmap() übergeben werden können. MAP_ALIGNED_SUPER ist nur unter FreeBSD verfügbar und MAP_CONCEAL ist nur unter OpenBSD verfügbar. Beachten Sie, dass einige Optionen auf bestimmten Systemen möglicherweise nicht vorhanden sind.

Geändert in Version 3.10: Konstante MAP_POPULATE hinzugefügt.

Hinzugefügt in Version 3.11: Konstante MAP_STACK hinzugefügt.

Hinzugefügt in Version 3.12: Konstanten MAP_ALIGNED_SUPER und MAP_CONCEAL hinzugefügt.

Hinzugefügt in Version 3.13: Konstanten MAP_32BIT, MAP_HASSEMAPHORE, MAP_JIT, MAP_NOCACHE, MAP_NOEXTEND, MAP_NORESERVE, MAP_RESILIENT_CODESIGN, MAP_RESILIENT_MEDIA, MAP_TPRO, MAP_TRANSLATED_ALLOW_EXECUTE und MAP_UNIX03 hinzugefügt.