shutil — High-level file operations

Source code: Lib/shutil.py

---

Das Modul shutil bietet eine Reihe von High-Level-Operationen für Dateien und Dateisammlungen. Insbesondere werden Funktionen zur Unterstützung von Dateioperationen wie Kopieren und Löschen bereitgestellt. Für Operationen auf einzelnen Dateien siehe auch das Modul os.

Warnung

Selbst die High-Level-Kopierfunktionen (shutil.copy(), shutil.copy2()) können nicht alle Metadaten einer Datei kopieren.

Auf POSIX-Plattformen bedeutet dies, dass der Dateibesitzer und die Gruppe sowie ACLs verloren gehen. Auf Mac OS werden der Ressourcen-Fork und andere Metadaten nicht verwendet. Dies bedeutet, dass Ressourcen verloren gehen und Datei- und Erstellungscodes nicht korrekt sind. Unter Windows werden Dateibesitzer, ACLs und alternative Datenströme nicht kopiert.

Verzeichnis- und Dateioperationen

shutil.copyfileobj(fsrc, fdst[, length])

Kopiert den Inhalt des file-like object fsrc in das file-like object fdst. Die Ganzzahl length ist, falls gegeben, die Puffergröße. Insbesondere bedeutet ein negativer length-Wert, dass die Daten ohne Schleifen über die Quelldaten in Chunks kopiert werden; standardmäßig werden die Daten in Chunks gelesen, um einen unkontrollierten Speicherverbrauch zu vermeiden. Beachten Sie, dass, wenn die aktuelle Dateiposition des fsrc-Objekts nicht 0 ist, nur der Inhalt von der aktuellen Dateiposition bis zum Ende der Datei kopiert wird.

copyfileobj() garantiert *nicht*, dass der Zielstream nach Abschluss des Kopiervorgangs geleert wurde. Wenn Sie nach Abschluss des Kopiervorgangs aus dem Ziel lesen möchten (z. B. den Inhalt einer temporären Datei, die aus einem HTTP-Stream kopiert wurde), müssen Sie sicherstellen, dass Sie flush() oder close() auf dem file-like object aufgerufen haben, bevor Sie versuchen, die Zieldatei zu lesen.

shutil.copyfile(src, dst, *, follow_symlinks=True)

Kopiert den Inhalt (keine Metadaten) der Datei src in eine Datei namens dst und gibt dst auf die effizienteste mögliche Weise zurück. src und dst sind pfadähnliche Objekte oder Pfadnamen, die als Strings angegeben sind.

dst muss der vollständige Zieldateiname sein; siehe copy() für eine Kopie, die einen Zielverzeichnispfad akzeptiert. Wenn src und dst dieselbe Datei angeben, wird SameFileError ausgelöst.

Der Zielort muss beschreibbar sein; andernfalls wird eine Ausnahme OSError ausgelöst. Wenn dst bereits existiert, wird es überschrieben. Spezialdateien wie Zeichen- oder Blockgeräte und Pipes können mit dieser Funktion nicht kopiert werden.

Wenn follow_symlinks falsch ist und src ein symbolischer Link ist, wird anstelle der Datei, auf die src verweist, ein neuer symbolischer Link erstellt.

Löst ein Auditing-Ereignis shutil.copyfile mit den Argumenten src, dst aus.

Geändert in Version 3.3: IOError wurde anstelle von OSError ausgelöst. Argument follow_symlinks hinzugefügt. Gibt nun dst zurück.

Geändert in Version 3.4: Löst SameFileError anstelle von Error aus. Da erstgenanntes eine Unterklasse von letzterem ist, ist diese Änderung abwärtskompatibel.

Geändert in Version 3.8: Plattformspezifische schnelle Kopiersystemaufrufe können intern verwendet werden, um die Datei effizienter zu kopieren. Siehe Abschnitt Plattformabhängige effiziente Kopiervorgänge.

exception shutil.SpecialFileError

Diese Ausnahme wird ausgelöst, wenn copyfile() oder copytree() versucht, eine benannte Pipe zu kopieren.

Hinzugefügt in Version 2.7.

exception shutil.SameFileError

Diese Ausnahme wird ausgelöst, wenn Quelle und Ziel in copyfile() dieselbe Datei sind.

Hinzugefügt in Version 3.4.

shutil.copymode(src, dst, *, follow_symlinks=True)

Kopiert die Berechtigungsbits von src nach dst. Der Dateiinhalt, der Besitzer und die Gruppe bleiben unverändert. src und dst sind pfadähnliche Objekte oder Pfadnamen, die als Strings angegeben sind. Wenn follow_symlinks falsch ist und sowohl src als auch dst symbolische Links sind, versucht copymode(), den Modus von dst selbst zu ändern (anstatt der Datei, auf die er verweist). Diese Funktionalität ist nicht auf jeder Plattform verfügbar; weitere Informationen finden Sie unter copystat(). Wenn copymode() symbolische Links auf der lokalen Plattform nicht ändern kann und dazu aufgefordert wird, tut er nichts und gibt zurück.

Löst ein Auditing-Ereignis shutil.copymode mit den Argumenten src, dst aus.

Geändert in Version 3.3: Argument follow_symlinks hinzugefügt.

shutil.copystat(src, dst, *, follow_symlinks=True)

Kopiert die Berechtigungsbits, die letzte Zugriffszeit, die letzte Änderungszeit und die Flags von src nach dst. Unter Linux kopiert copystat() auch die "erweiterten Attribute", wo möglich. Der Dateiinhalt, der Besitzer und die Gruppe bleiben unverändert. src und dst sind pfadähnliche Objekte oder Pfadnamen, die als Strings angegeben sind.

Wenn follow_symlinks falsch ist und src und dst beide auf symbolische Links verweisen, operiert copystat() auf den symbolischen Links selbst und nicht auf den Dateien, auf die die symbolischen Links verweisen — die Informationen werden vom src-Symboliklink gelesen und die Informationen in den dst-Symboliklink geschrieben.

Hinweis

Nicht alle Plattformen bieten die Möglichkeit, symbolische Links zu untersuchen und zu ändern. Python selbst kann Ihnen mitteilen, welche Funktionalität lokal verfügbar ist.

• Wenn os.chmod in os.supports_follow_symlinks True ist, kann copystat() die Berechtigungsbits eines symbolischen Links ändern.

• Wenn os.utime in os.supports_follow_symlinks True ist, kann copystat() die letzten Zugriffs- und Änderungszeiten eines symbolischen Links ändern.

• Wenn os.chflags in os.supports_follow_symlinks True ist, kann copystat() die Flags eines symbolischen Links ändern. (os.chflags ist nicht auf allen Plattformen verfügbar.)

Auf Plattformen, auf denen ein Teil oder die gesamte Funktionalität nicht verfügbar ist, kopiert copystat() alles, was er kann, wenn er aufgefordert wird, einen symbolischen Link zu ändern. copystat() gibt niemals einen Fehler zurück.

Siehe os.supports_follow_symlinks für weitere Informationen.

Löst ein Auditing-Ereignis shutil.copystat mit den Argumenten src, dst aus.

Geändert in Version 3.3: Argument follow_symlinks hinzugefügt und Unterstützung für Linux-erweiterte Attribute.

shutil.copy(src, dst, *, follow_symlinks=True)

Kopiert die Datei src in die Datei oder das Verzeichnis dst. src und dst sollten pfadähnliche Objekte oder Strings sein. Wenn dst ein Verzeichnis angibt, wird die Datei in dst unter Verwendung des Basisdateinamens von src kopiert. Wenn dst eine bereits existierende Datei angibt, wird diese überschrieben. Gibt den Pfad zur neu erstellten Datei zurück.

Wenn follow_symlinks falsch ist und src ein symbolischer Link ist, wird dst als symbolischer Link erstellt. Wenn follow_symlinks wahr ist und src ein symbolischer Link ist, ist dst eine Kopie der Datei, auf die src verweist.

copy() kopiert die Datei-Daten und den Berechtigungsmodus der Datei (siehe os.chmod()). Andere Metadaten, wie die Erstellungs- und Änderungszeiten der Datei, werden nicht beibehalten. Um alle Metadaten der Originaldatei beizubehalten, verwenden Sie stattdessen copy2().

Löst ein Auditing-Ereignis shutil.copyfile mit den Argumenten src, dst aus.

Löst ein Auditing-Ereignis shutil.copymode mit den Argumenten src, dst aus.

Geändert in Version 3.3: Argument follow_symlinks hinzugefügt. Gibt nun den Pfad zur neu erstellten Datei zurück.

Geändert in Version 3.8: Plattformspezifische schnelle Kopiersystemaufrufe können intern verwendet werden, um die Datei effizienter zu kopieren. Siehe Abschnitt Plattformabhängige effiziente Kopiervorgänge.

shutil.copy2(src, dst, *, follow_symlinks=True)

Identisch mit copy(), außer dass copy2() auch versucht, die Metadaten der Datei zu erhalten.

Wenn follow_symlinks falsch ist und src ein symbolischer Link ist, versucht copy2(), alle Metadaten vom symbolischen Link src auf den neu erstellten symbolischen Link dst zu kopieren. Diese Funktionalität ist jedoch nicht auf allen Plattformen verfügbar. Auf Plattformen, auf denen ein Teil oder die gesamte Funktionalität nicht verfügbar ist, behält copy2() alle Metadaten bei, die es kann; copy2() löst niemals eine Ausnahme aus, da es keine Dateimetadaten beibehalten kann.

copy2() verwendet copystat(), um die Dateimetadaten zu kopieren. Weitere Informationen zur plattformspezifischen Unterstützung für die Änderung von Metadaten von symbolischen Links finden Sie unter copystat().

Löst ein Auditing-Ereignis shutil.copyfile mit den Argumenten src, dst aus.

Löst ein Auditing-Ereignis shutil.copystat mit den Argumenten src, dst aus.

Geändert in Version 3.3: Argument follow_symlinks hinzugefügt, versucht auch, erweiterte Dateisystemattribute zu kopieren (derzeit nur Linux). Gibt nun den Pfad zur neu erstellten Datei zurück.

Geändert in Version 3.8: Plattformspezifische schnelle Kopiersystemaufrufe können intern verwendet werden, um die Datei effizienter zu kopieren. Siehe Abschnitt Plattformabhängige effiziente Kopiervorgänge.

shutil.ignore_patterns(*patterns)

Diese Factory-Funktion erstellt eine Funktion, die als aufrufbares Objekt für das ignore-Argument von copytree() verwendet werden kann und Dateien und Verzeichnisse ignoriert, die einem der angegebenen Glob-Muster entsprechen. Siehe das Beispiel unten.

shutil.copytree(src, dst, symlinks=False, ignore=None, copy_function=copy2, ignore_dangling_symlinks=False, dirs_exist_ok=False)

Kopiert rekursiv einen gesamten Verzeichnisbaum, der von src ausgeht, in ein Verzeichnis namens dst und gibt das Zielverzeichnis zurück. Alle Zwischenverzeichnisse, die benötigt werden, um dst zu enthalten, werden standardmäßig ebenfalls erstellt.

Berechtigungen und Zeiten von Verzeichnissen werden mit copystat() kopiert, einzelne Dateien werden mit copy2() kopiert.

Wenn symlinks wahr ist, werden symbolische Links im Quellverzeichnisbaum als symbolische Links im neuen Baum dargestellt und die Metadaten der ursprünglichen Links werden so weit wie die Plattform es zulässt kopiert; wenn falsch oder weggelassen, werden die Inhalte und Metadaten der verknüpften Dateien in den neuen Baum kopiert.

Wenn symlinks falsch ist und die Datei, auf die der Symlink verweist, nicht existiert, wird eine Ausnahme in die Liste der Fehler aufgenommen, die am Ende des Kopiervorgangs in einer Error-Ausnahme ausgelöst werden. Sie können das optionale Flag ignore_dangling_symlinks auf wahr setzen, wenn Sie diese Ausnahme unterdrücken möchten. Beachten Sie, dass diese Option auf Plattformen, die os.symlink() nicht unterstützen, keine Auswirkung hat.

Wenn ignore angegeben ist, muss es ein aufrufbares Objekt sein, das als Argumente das Verzeichnis, das von copytree() besucht wird, und eine Liste seines Inhalts, wie von os.listdir() zurückgegeben, erhält. Da copytree() rekursiv aufgerufen wird, wird das ignore-Objekt einmal für jedes Verzeichnis aufgerufen, das kopiert wird. Das aufrufbare Objekt muss eine Sequenz von Verzeichnis- und Dateinamen relativ zum aktuellen Verzeichnis zurückgeben (d. h. eine Teilmenge der Elemente in seinem zweiten Argument); diese Namen werden dann im Kopiervorgang ignoriert. ignore_patterns() kann verwendet werden, um ein solches aufrufbares Objekt zu erstellen, das Namen basierend auf Glob-ähnlichen Mustern ignoriert.

Wenn Ausnahmen auftreten, wird eine Error mit einer Liste von Gründen ausgelöst.

Wenn copy_function angegeben ist, muss es ein aufrufbares Objekt sein, das verwendet wird, um jede Datei zu kopieren. Es wird mit dem Quellpfad und dem Zielpfad als Argumenten aufgerufen. Standardmäßig wird copy2() verwendet, aber jede Funktion, die dieselbe Signatur unterstützt (wie copy()), kann verwendet werden.

Wenn dirs_exist_ok falsch ist (Standard) und dst bereits existiert, wird FileExistsError ausgelöst. Wenn dirs_exist_ok wahr ist, wird der Kopiervorgang fortgesetzt, wenn vorhandene Verzeichnisse angetroffen werden, und Dateien im dst-Baum werden durch entsprechende Dateien aus dem src-Baum überschrieben.

Löst ein Auditing-Ereignis shutil.copytree mit den Argumenten src, dst aus.

Geändert in Version 3.2: Argument copy_function hinzugefügt, um eine benutzerdefinierte Kopierfunktion bereitstellen zu können. Argument ignore_dangling_symlinks hinzugefügt, um Fehler bei hängenden symbolischen Links zu unterdrücken, wenn symlinks falsch ist.

Geändert in Version 3.3: Metadaten kopieren, wenn symlinks falsch ist. Gibt nun dst zurück.

Geändert in Version 3.8: Plattformspezifische schnelle Kopiersystemaufrufe können intern verwendet werden, um die Datei effizienter zu kopieren. Siehe Abschnitt Plattformabhängige effiziente Kopiervorgänge.

Geändert in Version 3.8: Parameter dirs_exist_ok hinzugefügt.

shutil.rmtree(path, ignore_errors=False, onerror=None, *, onexc=None, dir_fd=None)

Löscht einen gesamten Verzeichnisbaum; path muss auf ein Verzeichnis zeigen (aber nicht auf einen symbolischen Link zu einem Verzeichnis). Wenn ignore_errors wahr ist, werden Fehler bei fehlgeschlagenen Löschungen ignoriert; wenn falsch oder weggelassen, werden solche Fehler durch Aufruf eines von onexc oder onerror angegebenen Handlers behandelt, oder, wenn beides weggelassen wird, werden Ausnahmen an den Aufrufer weitergegeben.

Diese Funktion kann Pfade relativ zu Verzeichnis-Deskriptoren unterstützen.

Hinweis

Auf Plattformen, die die notwendigen fd-basierten Funktionen unterstützen, wird standardmäßig eine symlink-attackenresistente Version von rmtree() verwendet. Auf anderen Plattformen ist die Implementierung von rmtree() anfällig für Symlink-Angriffe: mit dem richtigen Timing und den richtigen Umständen können Angreifer Symlinks auf dem Dateisystem manipulieren, um Dateien zu löschen, auf die sie sonst keinen Zugriff hätten. Anwendungen können die Funktionseigenschaft rmtree.avoids_symlink_attacks verwenden, um festzustellen, welcher Fall zutrifft.

Wenn onexc bereitgestellt wird, muss es sich um ein aufrufbares Objekt handeln, das drei Parameter akzeptiert: function, path und excinfo.

Der erste Parameter, function, ist die Funktion, die die Ausnahme ausgelöst hat; sie hängt von der Plattform und der Implementierung ab. Der zweite Parameter, path, ist der an function übergebene Pfadname. Der dritte Parameter, excinfo, ist die ausgelöste Ausnahme. Von onexc ausgelöste Ausnahmen werden nicht abgefangen.

Das veraltete onerror ist ähnlich wie onexc, mit dem Unterschied, dass der dritte Parameter, den es erhält, das von sys.exc_info() zurückgegebene Tupel ist.

Siehe auch

rmtree-Beispiel für ein Beispiel zur Handhabung der Entfernung eines Verzeichnisbaums, der schreibgeschützte Dateien enthält.

Löst ein Auditing-Ereignis shutil.rmtree mit den Argumenten path, dir_fd aus.

Geändert in Version 3.3: Eine symlink-attackenresistente Version wurde hinzugefügt, die automatisch verwendet wird, wenn die Plattform fd-basierte Funktionen unterstützt.

Geändert in Version 3.8: Unter Windows wird der Inhalt einer Verzeichnisschleife nicht mehr gelöscht, bevor die Schleife entfernt wird.

Geändert in Version 3.11: Parameter dir_fd hinzugefügt.

Geändert in Version 3.12: Parameter onexc hinzugefügt, onerror als veraltet markiert.

Geändert in Version 3.13: rmtree() ignoriert nun FileNotFoundError-Ausnahmen für alle Pfade außer dem obersten Pfad. Ausnahmen, die nicht OSError und Unterklassen von OSError sind, werden nun immer an den Aufrufer weitergegeben.

rmtree.avoids_symlink_attacks

Gibt an, ob die aktuelle Plattform und Implementierung eine symlink-attackenresistente Version von rmtree() bereitstellt. Derzeit ist dies nur auf Plattformen wahr, die fd-basierte Verzeichniszugriffsfunktionen unterstützen.

Hinzugefügt in Version 3.3.

shutil.move(src, dst, copy_function=copy2)

Verschiebt rekursiv eine Datei oder ein Verzeichnis (src) an einen anderen Ort und gibt das Ziel zurück.

Wenn dst ein existierendes Verzeichnis oder ein symbolischer Link zu einem Verzeichnis ist, wird src in dieses Verzeichnis verschoben. Der Zielpfad in diesem Verzeichnis darf noch nicht existieren.

Wenn dst bereits existiert, aber kein Verzeichnis ist, kann es je nach Semantik von os.rename() überschrieben werden.

Wenn das Ziel auf dem aktuellen Dateisystem liegt, wird os.rename() verwendet. Andernfalls wird src mit copy_function an das Ziel kopiert und dann entfernt. Im Falle von symbolischen Links wird ein neuer symbolischer Link, der auf das Ziel von src verweist, als Ziel erstellt und src wird entfernt.

Wenn copy_function angegeben ist, muss es sich um ein aufrufbares Objekt handeln, das zwei Argumente (src und das Ziel) annimmt und verwendet wird, um src an das Ziel zu kopieren, wenn os.rename() nicht verwendet werden kann. Wenn die Quelle ein Verzeichnis ist, wird copytree() aufgerufen und die copy_function übergeben. Die Standard-copy_function ist copy2(). Die Verwendung von copy() als copy_function ermöglicht den Erfolg des Verschiebevorgangs, wenn die Metadaten nicht kopiert werden können, auf Kosten des Nichtkopierens aller Metadaten.

Löst ein Auditing-Ereignis shutil.move mit den Argumenten src, dst aus.

Geändert in Version 3.3: Explizite Behandlung von symbolischen Links für fremde Dateisysteme hinzugefügt, wodurch sie an das Verhalten von GNU's mv angepasst wird. Gibt nun dst zurück.

Geändert in Version 3.5: Schlüsselwortargument copy_function hinzugefügt.

Geändert in Version 3.8: Plattformspezifische schnelle Kopiersystemaufrufe können intern verwendet werden, um die Datei effizienter zu kopieren. Siehe Abschnitt Plattformabhängige effiziente Kopiervorgänge.

Geändert in Version 3.9: Akzeptiert ein pfadähnliches Objekt für src und dst.

shutil.disk_usage(path)

Gibt die Speicherplatznutzungsstatistiken für den angegebenen Pfad als named tuple mit den Attributen total, used und free zurück, die die Menge des gesamten, genutzten und freien Speicherplatzes in Bytes darstellen. path kann eine Datei oder ein Verzeichnis sein.

Hinweis

Auf Unix-Dateisystemen muss path auf einen Pfad innerhalb einer **eingebundenen** Dateisystempartition zeigen. Auf diesen Plattformen versucht CPython nicht, Speicherplatzinformationen von nicht eingebundenen Dateisystemen abzurufen.

Hinzugefügt in Version 3.3.

Geändert in Version 3.8: Unter Windows kann path nun eine Datei oder ein Verzeichnis sein.

Verfügbarkeit: Unix, Windows.

shutil.chown(path, user=None, group=None, *, dir_fd=None, follow_symlinks=True)

Ändert den Besitzer user und/oder die Gruppe group des gegebenen path.

user kann ein Systembenutzername oder eine UID sein; das Gleiche gilt für group. Mindestens ein Argument ist erforderlich.

Siehe auch os.chown(), die zugrundeliegende Funktion.

Löst ein Audit-Ereignis shutil.chown mit den Argumenten path, user, group aus.

Verfügbarkeit: Unix.

Hinzugefügt in Version 3.3.

Geändert in Version 3.13: Hinzugefügt wurden die Parameter dir_fd und follow_symlinks.

shutil.which(cmd, mode=os.F_OK | os.X_OK, path=None)

Gibt den Pfad zu einer ausführbaren Datei zurück, die ausgeführt würde, wenn der gegebene cmd aufgerufen würde. Wenn kein cmd ausgeführt würde, wird None zurückgegeben.

mode ist eine Berechtigungsmaske, die an os.access() übergeben wird und standardmäßig bestimmt, ob die Datei existiert und ausführbar ist.

path ist eine „PATH-Zeichenkette“, die die zu durchsuchenden Verzeichnisse angibt, getrennt durch os.pathsep. Wenn kein path angegeben ist, wird die Umgebungsvariable PATH aus os.environ gelesen, und falls diese nicht gesetzt ist, wird auf os.defpath zurückgegriffen.

Wenn cmd eine Verzeichniskomponente enthält, prüft which() nur den angegebenen Pfad direkt und durchsucht nicht die Verzeichnisse, die in path oder in der System-Umgebungsvariable PATH aufgeführt sind.

Unter Windows wird das aktuelle Verzeichnis dem path vorangestellt, wenn mode nicht os.X_OK enthält. Wenn mode os.X_OK enthält, wird die Windows-API NeedCurrentDirectoryForExePathW konsultiert, um festzustellen, ob das aktuelle Verzeichnis dem path vorangestellt werden soll. Um das aktuelle Arbeitsverzeichnis für ausführbare Dateien nicht zu konsultieren: setzen Sie die Umgebungsvariable NoDefaultCurrentDirectoryInExePath.

Ebenfalls unter Windows wird die Umgebungsvariable PATHEXT verwendet, um Befehle aufzulösen, die möglicherweise noch keine Erweiterung enthalten. Wenn Sie beispielsweise shutil.which("python") aufrufen, durchsucht which() PATHEXT, um zu wissen, dass es nach python.exe in den path-Verzeichnissen suchen sollte. Zum Beispiel unter Windows

>>> shutil.which("python")
'C:\\Python33\\python.EXE'

Dies gilt auch, wenn cmd ein Pfad mit einer Verzeichniskomponente ist

>>> shutil.which("C:\\Python33\\python")
'C:\\Python33\\python.EXE'

Hinzugefügt in Version 3.3.

Geändert in Version 3.8: Der Typ bytes wird jetzt akzeptiert. Wenn der Typ von cmd bytes ist, ist auch der Ergebnistyp bytes.

Geändert in Version 3.12: Unter Windows wird das aktuelle Verzeichnis nicht mehr dem Suchpfad vorangestellt, wenn mode os.X_OK enthält und die WinAPI NeedCurrentDirectoryForExePathW(cmd) falsch ist, andernfalls wird das aktuelle Verzeichnis vorangestellt, auch wenn es bereits im Suchpfad enthalten ist; PATHEXT wird jetzt auch verwendet, wenn cmd eine Verzeichniskomponente enthält oder mit einer Erweiterung endet, die in PATHEXT enthalten ist; und Dateinamen ohne Erweiterung können nun gefunden werden.

exception shutil.Error

Diese Ausnahme sammelt Ausnahmen, die während eines Multi-Datei-Vorgangs ausgelöst werden. Für copytree() ist das Ausnahmenargument eine Liste von 3-Tupeln (srcname, dstname, exception).

Plattformabhängige effiziente Kopieroperationen

Ab Python 3.8 können alle Funktionen, die eine Dateikopie beinhalten (copyfile(), copy(), copy2(), copytree() und move()) plattformspezifische „Fast-Copy“-Systemaufrufe verwenden, um die Datei effizienter zu kopieren (siehe bpo-33671). „Fast-Copy“ bedeutet, dass die Kopieroperation im Kernel stattfindet und die Verwendung von Userspace-Puffern in Python, wie bei „outfd.write(infd.read())“, vermieden wird.

Unter macOS wird fcopyfile zum Kopieren des Dateiinhalts (nicht der Metadaten) verwendet.

Unter Linux werden os.copy_file_range() oder os.sendfile() verwendet.

Unter Solaris wird os.sendfile() verwendet.

Unter Windows verwendet shutil.copyfile() eine größere Standardpuffergröße (1 MiB anstelle von 64 KiB) und eine memoryview()-basierte Variante von shutil.copyfileobj().

Wenn der Fast-Copy-Vorgang fehlschlägt und keine Daten in die Zieldatei geschrieben wurden, greift shutil intern leise auf die weniger effiziente Funktion copyfileobj() zurück.

Geändert in Version 3.8.

Geändert in Version 3.14: Solaris verwendet jetzt os.sendfile().

Geändert in Version 3.14: Copy-on-write oder serverseitiges Kopieren kann intern über os.copy_file_range() auf unterstützten Linux-Dateisystemen verwendet werden.

Beispiel für `copytree`

Ein Beispiel, das die Hilfsfunktion ignore_patterns() verwendet

from shutil import copytree, ignore_patterns

copytree(source, destination, ignore=ignore_patterns('*.pyc', 'tmp*'))

Dies kopiert alles außer .pyc-Dateien und Dateien oder Verzeichnissen, deren Name mit tmp beginnt.

Ein weiteres Beispiel, das das ignore-Argument verwendet, um einen Logging-Aufruf hinzuzufügen

from shutil import copytree
import logging

def _logpath(path, names):
    logging.info('Working in %s', path)
    return []   # nothing will be ignored

copytree(source, destination, ignore=_logpath)

Beispiel für `rmtree`

Dieses Beispiel zeigt, wie ein Verzeichnisbaum unter Windows gelöscht wird, bei dem einige Dateien ihr schreibgeschütztes Bit gesetzt haben. Es verwendet den Callback `onexc`, um das schreibgeschützte Bit zu löschen und den Löschvorgang erneut zu versuchen. Jeder nachfolgende Fehler wird weitergegeben.

import os, stat
import shutil

def remove_readonly(func, path, _):
    "Clear the readonly bit and reattempt the removal"
    os.chmod(path, stat.S_IWRITE)
    func(path)

shutil.rmtree(directory, onexc=remove_readonly)

Archivierungsoperationen

Hinzugefügt in Version 3.2.

Geändert in Version 3.5: Unterstützung für das Format xztar hinzugefügt.

Es werden auch High-Level-Utilities zum Erstellen und Lesen von komprimierten und archivierten Dateien bereitgestellt. Sie basieren auf den Modulen zipfile und tarfile.

shutil.make_archive(base_name, format[, root_dir[, base_dir[, verbose[, dry_run[, owner[, group[, logger]]]]]]]])

Erstellt eine Archivdatei (wie z.B. zip oder tar) und gibt ihren Namen zurück.

base_name ist der Name der zu erstellenden Datei, einschließlich des Pfades, ohne eine formatspezifische Erweiterung.

format ist das Archivformat: eines von „zip“ (wenn das Modul zlib verfügbar ist), „tar“, „gztar“ (wenn das Modul zlib verfügbar ist), „bztar“ (wenn das Modul bz2 verfügbar ist), „xztar“ (wenn das Modul lzma verfügbar ist) oder „zstdtar“ (wenn das Modul compression.zstd verfügbar ist).

root_dir ist ein Verzeichnis, das das Stammverzeichnis des Archivs sein wird; alle Pfade im Archiv werden relativ dazu sein; zum Beispiel wechseln wir typischerweise in root_dir, bevor wir das Archiv erstellen.

base_dir ist das Verzeichnis, von dem aus wir die Archivierung starten; d.h. base_dir wird das gemeinsame Präfix aller Dateien und Verzeichnisse im Archiv sein. base_dir muss relativ zu root_dir angegeben werden. Siehe Archivierungsbeispiel mit base_dir für die Verwendung von base_dir und root_dir zusammen.

root_dir und base_dir sind standardmäßig das aktuelle Verzeichnis.

Wenn dry_run wahr ist, wird kein Archiv erstellt, aber die auszuführenden Operationen werden in logger protokolliert.

owner und group werden beim Erstellen eines Tar-Archivs verwendet. Standardmäßig wird der aktuelle Besitzer und die aktuelle Gruppe verwendet.

logger muss ein Objekt sein, das mit PEP 282 kompatibel ist, normalerweise eine Instanz von logging.Logger.

Das Argument verbose wird nicht verwendet und ist veraltet.

Löst ein Audit-Ereignis shutil.make_archive mit den Argumenten base_name, format, root_dir, base_dir aus.

Hinweis

Diese Funktion ist nicht thread-sicher, wenn benutzerdefinierte Archiver, die mit register_archive_format() registriert wurden, das Argument root_dir nicht unterstützen. In diesem Fall wird das aktuelle Arbeitsverzeichnis des Prozesses vorübergehend nach root_dir geändert, um die Archivierung durchzuführen.

Geändert in Version 3.8: Das moderne pax (POSIX.1-2001) Format wird nun anstelle des Legacy-GNU-Formats für Archive verwendet, die mit format="tar" erstellt wurden.

Geändert in Version 3.10.6: Diese Funktion ist nun thread-sicher bei der Erstellung von Standard .zip- und Tar-Archiven.

shutil.get_archive_formats()

Gibt eine Liste der unterstützten Formate für die Archivierung zurück. Jedes Element der zurückgegebenen Sequenz ist ein Tupel (name, description).

Standardmäßig bietet shutil diese Formate an

• zip: ZIP-Datei (wenn das Modul zlib verfügbar ist).

• tar: Unkomprimierte Tar-Datei. Verwendet das POSIX.1-2001 pax-Format für neue Archive.

• gztar: Gzip-komprimierte Tar-Datei (wenn das Modul zlib verfügbar ist).

• bztar: Bzip2-komprimierte Tar-Datei (wenn das Modul bz2 verfügbar ist).

• xztar: XZ-komprimierte Tar-Datei (wenn das Modul lzma verfügbar ist).

• zstdtar: Zstandard-komprimierte Tar-Datei (wenn das Modul compression.zstd verfügbar ist).

Sie können neue Formate registrieren oder Ihren eigenen Archiver für bestehende Formate bereitstellen, indem Sie register_archive_format() verwenden.

shutil.register_archive_format(name, function[, extra_args[, description]])

Registriert einen Archiver für das Format name.

function ist der aufrufbare Teil, der zum Entpacken von Archiven verwendet wird. Der aufrufbare Teil erhält den base_name der zu erstellenden Datei, gefolgt von base_dir (der standardmäßig os.curdir ist), von dem aus archiviert werden soll. Weitere Argumente werden als Schlüsselwortargumente übergeben: owner, group, dry_run und logger (wie in make_archive() übergeben).

Wenn function das benutzerdefinierte Attribut function.supports_root_dir auf True gesetzt hat, wird das Argument root_dir als Schlüsselwortargument übergeben. Andernfalls wird das aktuelle Arbeitsverzeichnis des Prozesses vorübergehend nach root_dir geändert, bevor function aufgerufen wird. In diesem Fall ist make_archive() nicht thread-sicher.

Wenn angegeben, ist extra_args eine Sequenz von Paaren (name, value), die als zusätzliche Schlüsselwortargumente verwendet werden, wenn der Archiver-Callable verwendet wird.

description wird von get_archive_formats() verwendet, das die Liste der Archiver zurückgibt. Standardmäßig ist es eine leere Zeichenkette.

Geändert in Version 3.12: Unterstützung für Funktionen hinzugefügt, die das Argument root_dir unterstützen.

shutil.unregister_archive_format(name)

Entfernt das Archivformat name aus der Liste der unterstützten Formate.

shutil.unpack_archive(filename[, extract_dir[, format[, filter]]])

Entpackt ein Archiv. filename ist der vollständige Pfad des Archivs.

extract_dir ist der Name des Zielverzeichnisses, in das das Archiv entpackt wird. Wenn nicht angegeben, wird das aktuelle Arbeitsverzeichnis verwendet.

format ist das Archivformat: eines von „zip“, „tar“, „gztar“, „bztar“, „xztar“ oder „zstdtar“. Oder jedes andere Format, das mit register_unpack_format() registriert wurde. Wenn nicht angegeben, verwendet unpack_archive() die Dateierweiterung des Archivs und prüft, ob ein Entpacker für diese Erweiterung registriert wurde. Wenn keiner gefunden wird, wird ein ValueError ausgelöst.

Das schlüsselwortbasierte Argument filter wird an die zugrundeliegende Entpackungsfunktion übergeben. Für Zip-Dateien wird filter nicht akzeptiert. Für Tar-Dateien wird die Verwendung von 'data' (Standard seit Python 3.14) empfohlen, es sei denn, Sie verwenden Tar-spezifische Funktionen und UNIX-ähnliche Dateisysteme. (Details siehe Extraktionsfilter.)

Löst ein Audit-Ereignis shutil.unpack_archive mit den Argumenten filename, extract_dir, format aus.

Warnung

Extrahieren Sie niemals Archive aus nicht vertrauenswürdigen Quellen ohne vorherige Prüfung. Es ist möglich, dass Dateien außerhalb des in extract_dir angegebenen Pfades erstellt werden, z.B. Mitglieder mit absoluten Dateinamen, die mit "/" beginnen, oder Dateinamen mit zwei Punkten "..".

Seit Python 3.14 verhindern die Standardeinstellungen für beide integrierten Formate (Zip- und Tar-Dateien) die gefährlichsten dieser Sicherheitsprobleme, verhindern aber nicht alle unbeabsichtigten Verhaltensweisen. Lesen Sie den Abschnitt Hinweise zur weiteren Verifizierung für Tar-spezifische Details.

Geändert in Version 3.7: Akzeptiert ein pfadähnliches Objekt für filename und extract_dir.

Geändert in Version 3.12: Das Argument filter wurde hinzugefügt.

shutil.register_unpack_format(name, extensions, function[, extra_args[, description]])

Registriert ein Entpackformat. name ist der Name des Formats und extensions ist eine Liste von Erweiterungen, die dem Format entsprechen, wie z.B. .zip für Zip-Dateien.

function ist der aufrufbare Teil, der zum Entpacken von Archiven verwendet wird. Der aufrufbare Teil empfängt

• den Pfad des Archivs als Positionsargument;

• das Verzeichnis, in das das Archiv extrahiert werden soll, als Positionsargument;

• möglicherweise ein Schlüsselwortargument filter, wenn es an unpack_archive() übergeben wurde;

• zusätzliche Schlüsselwortargumente, die durch extra_args als Sequenz von Tupeln (name, value) angegeben werden.

description kann zur Beschreibung des Formats angegeben werden und wird von der Funktion get_unpack_formats() zurückgegeben.

shutil.unregister_unpack_format(name)

Entregistriert ein Entpackformat. name ist der Name des Formats.

shutil.get_unpack_formats()

Gibt eine Liste aller registrierten Formate zum Entpacken zurück. Jedes Element der zurückgegebenen Sequenz ist ein Tupel (name, extensions, description).

Standardmäßig bietet shutil diese Formate an

• zip: ZIP-Datei (das Entpacken von komprimierten Dateien funktioniert nur, wenn das entsprechende Modul verfügbar ist).

• tar: unkomprimierte Tar-Datei.

• gztar: Gzip-komprimierte Tar-Datei (wenn das Modul zlib verfügbar ist).

• bztar: Bzip2-komprimierte Tar-Datei (wenn das Modul bz2 verfügbar ist).

• xztar: XZ-komprimierte Tar-Datei (wenn das Modul lzma verfügbar ist).

• zstdtar: Zstandard-komprimierte Tar-Datei (wenn das Modul compression.zstd verfügbar ist).

Sie können neue Formate registrieren oder Ihren eigenen Entpacker für bestehende Formate bereitstellen, indem Sie register_unpack_format() verwenden.

Archivierungsbeispiel

In diesem Beispiel erstellen wir ein gzip-komprimiertes Tar-Archiv, das alle Dateien im Verzeichnis .ssh des Benutzers enthält

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> root_dir = os.path.expanduser(os.path.join('~', '.ssh'))
>>> make_archive(archive_name, 'gztar', root_dir)
'/Users/tarek/myarchive.tar.gz'

Das resultierende Archiv enthält

$ tar -tzvf /Users/tarek/myarchive.tar.gz
drwx------ tarek/staff       0 2010-02-01 16:23:40 ./
-rw-r--r-- tarek/staff     609 2008-06-09 13:26:54 ./authorized_keys
-rwxr-xr-x tarek/staff      65 2008-06-09 13:26:54 ./config
-rwx------ tarek/staff     668 2008-06-09 13:26:54 ./id_dsa
-rwxr-xr-x tarek/staff     609 2008-06-09 13:26:54 ./id_dsa.pub
-rw------- tarek/staff    1675 2008-06-09 13:26:54 ./id_rsa
-rw-r--r-- tarek/staff     397 2008-06-09 13:26:54 ./id_rsa.pub
-rw-r--r-- tarek/staff   37192 2010-02-06 18:23:10 ./known_hosts

Archivierungsbeispiel mit base_dir

In diesem Beispiel, ähnlich dem oben, zeigen wir, wie make_archive() verwendet wird, aber diesmal mit der Verwendung von base_dir. Wir haben nun die folgende Verzeichnisstruktur

$ tree tmp
tmp
└── root
    └── structure
        ├── content
            └── please_add.txt
        └── do_not_add.txt

Im endgültigen Archiv sollte please_add.txt enthalten sein, aber do_not_add.txt nicht. Daher verwenden wir Folgendes

>>> from shutil import make_archive
>>> import os
>>> archive_name = os.path.expanduser(os.path.join('~', 'myarchive'))
>>> make_archive(
...     archive_name,
...     'tar',
...     root_dir='tmp/root',
...     base_dir='structure/content',
... )
'/Users/tarek/myarchive.tar'

Das Auflisten der Dateien im resultierenden Archiv ergibt

$ python -m tarfile -l /Users/tarek/myarchive.tar
structure/content/
structure/content/please_add.txt

Abfragen der Größe des Ausgabeterminals

shutil.get_terminal_size(fallback=(columns, lines))

Ruft die Größe des Terminalfensters ab.

Für jede der beiden Dimensionen wird die Umgebungsvariable COLUMNS bzw. LINES geprüft. Wenn die Variable definiert ist und der Wert eine positive Ganzzahl ist, wird sie verwendet.

Wenn COLUMNS oder LINES nicht definiert ist, was der übliche Fall ist, wird das an sys.__stdout__ angeschlossene Terminal durch Aufruf von os.get_terminal_size() abgefragt.

Wenn die Terminalgröße nicht erfolgreich abgefragt werden kann, entweder weil das System die Abfrage nicht unterstützt oder weil wir nicht mit einem Terminal verbunden sind, wird der im Parameter fallback angegebene Wert verwendet. fallback ist standardmäßig (80, 24), was die Standardgröße ist, die von vielen Terminalemulatoren verwendet wird.

Der zurückgegebene Wert ist ein benanntes Tupel vom Typ os.terminal_size.

Siehe auch: Die Single UNIX Specification, Version 2, Andere Umgebungsvariablen.

Hinzugefügt in Version 3.3.

Geändert in Version 3.11: Die fallback-Werte werden auch verwendet, wenn os.get_terminal_size() Nullen zurückgibt.