Sichere plattformübergreifende Pfadbehandlung in Python mit pathlib

Reine Pfade versus konkrete Pfade: Die richtige Klasse wählen

pathlib teilt seine API in zwei Familien auf. PurePath und seine Unterklassen (PurePosixPath, PureWindowsPath) führen nur zeichenkettenbasierte Berechnungen wie Zusammenfügen, Aufteilen und Ersetzen von Suffixen durch und lösen keine Systemaufrufe aus. Path, PosixPath und WindowsPath erben von den reinen Klassen und fügen I/O-Methoden wie open, read_text und mkdir hinzu.

Die entscheidende Erkenntnis für Plattformübergreifendheit ist, dass Sie jede reine Variante auf jedem Betriebssystem instanziieren können. Auf einem Linux-Rechner können Sie kein WindowsPath erstellen, da dies einen windows-spezifischen Systemaufruf versuchen würde, aber PureWindowsPath funktioniert überall. Dies ermöglicht es Ihnen, einen Windows-UNC-Pfad in einer reinen Unix-Testumgebung zu validieren, normalisieren oder transformieren, ohne das Dateisystem zu berühren.

Laut der pathlib-Dokumentation sind reine Pfade nützlich, wenn Sie Windows-Pfade auf einem Unix-Rechner manipulieren möchten oder sicherstellen müssen, dass Ihr Code niemals OS-zugreifende Operationen ausführt. Konkrete Pfade sollten für den Moment reserviert bleiben, in dem Sie tatsächlich mit dem Dateisystem interagieren müssen.

from pathlib import Path, PureWindowsPath, PurePosixPath, UnsupportedOperation, NotImplementedError  # noqa: F401 (illustrative imports only)

Existenz und Typ ohne Race Conditions prüfen

exists(), is_file() und is_dir() geben Booleans zurück, indem sie intern stat aufrufen. Sie sind praktisch für schnelle Diagnosen, führen aber eine Zeit-von-Prüfung-bis-Zeit-der-Nutzung-Race-Condition ein: Ein anderer Prozess oder Thread kann die Datei zwischen der Prüfung und dem anschließenden open löschen oder ersetzen. Die pathlib-Dokumentation weist darauf hin, dass Methoden konkreter Pfade OSError auslösen können, wenn ein Systemaufruf fehlschlägt.

Das sicherere Muster besteht darin, die Operation direkt innerhalb eines try/except-OSError-Blocks zu versuchen. Wenn Sie zuerst prüfen müssen (zum Beispiel um zu entscheiden, ob erstellt oder gelesen wird), halten Sie das Fenster zwischen Prüfung und Aktion so klein wie möglich und umschließen Sie die Aktion dennoch mit Exception-Handling.

from pathlib import Path

target = Path('output/report.csv')

# Preferred: attempt and handle failure
try:
    content = target.read_text(encoding='utf-8')
except FileNotFoundError:
    print(f'{target} does not exist yet')
except PermissionError:
    print(f'No permission to read {target}')
except OSError as exc:
    print(f'OS error on {target}: {exc}')

Erweiterungen sicher ändern mit with_suffix, with_name und with_stem

with_suffix ersetzt das vorhandene Suffix oder fügt eines hinzu, wenn keines vorhanden ist. Die Übergabe eines leeren Strings entfernt das Suffix vollständig. Die Methode betrachtet nur das letzte Punktsegment, daher ist bei einer Datei namens archive.tar.gz das Suffix '.gz', und with_suffix('.bz2') ergibt archive.tar.bz2, nicht archive.bz2.

with_name ersetzt die gesamte letzte Komponente einschließlich aller Suffixe. with_stem (hinzugefügt in Python 3.9) ändert nur den Teil vor dem Suffix und behält dieses bei. Beide lösen ValueError aus, wenn der Pfad keine Namenskomponente hat, wie etwa eine bloße Laufwerkswurzel wie C:/.

Ein häufiger Fehler ist die Annahme, dass with_suffix Mehrlagen-Erweiterungen wie .tar.gz als Einheit behandelt. Das tut es nicht; Sie müssen with_name oder manuelle Stem-Konstruktion für zusammengesetzte Erweiterungen verwenden.

from pathlib import PureWindowsPath

p = PureWindowsPath('c:/Downloads/archive.tar.gz')
print(p.with_suffix('.bz2'))   # c:/Downloads/archive.tar.bz2
print(p.with_stem('backup'))   # c:/Downloads/backup.gz
print(p.with_name('new.txt'))  # c:/Downloads/new.txt

Navigieren von Verzeichnisbäumen mit iterdir und glob

glob akzeptiert Shell-artige Muster; '' bedeutet dieses Verzeichnis und alle Unterverzeichnisse rekursiv, und recursive=True ist standardmäßig aktiviert, sodass glob('/*.py') den gesamten Baum ohne expliziten Flag durchsucht. rglob ist eine Abkürzung für glob('**/pattern').

Ergebnisse von iterdir und glob werden in beliebiger Reihenfolge zurückgegeben und können versteckte Einträge enthalten (Dotfiles auf Unix, Dateien mit dem Attribut 'hidden' auf Windows). Wenn Sie eine deterministische Reihenfolge benötigen, sortieren Sie die Ergebnisse explizit. Ob glob symbolische Links folgt, kann je nach Python-Version variieren, überprüfen Sie also das Verhalten anhand der pathlib-Dokumentation für die von Ihnen verwendete Version, anstatt eine feste Regel anzunehmen.

from pathlib import Path

data_dir = Path('output')
for p in sorted(data_dir.iterdir()):
    if p.is_file() and p.suffix == '.csv':
        print(p.resolve())

# Recursive search for all Python files
for py in data_dir.rglob('*.py'):
    print(py)

Auflösen von Pfaden: absolute, resolve, expanduser und home

absolute() stellt das aktuelle Arbeitsverzeichnis voran, ohne Dot-Dot-Segmente zu normalisieren oder Symlinks zu folgen. resolve() eliminiert '..'-Komponenten und folgt jedem Symlink, dem es begegnet, und gibt einen kanonischen Pfad zurück. In Python 3.6 wurde der Parameter strict hinzugefügt; mit strict=True löst ein fehlender Pfad oder ein Symlink-Loop OSError aus, während das Standardverhalten strict=False so weit wie möglich auflöst und den Rest anhängt.

expanduser() ersetzt eine führende Tilde oder Tilde-Benutzer-Konstruktion durch das entsprechende Home-Verzeichnis. home() ist eine Classmethod, die den aktuellen Benutzer-Home-Pfad direkt zurückgibt. Beide lösen RuntimeError aus, wenn das Home-Verzeichnis nicht bestimmt werden kann.

from pathlib import Path

p = Path('docs/../setup.py')
print(p.resolve())          # /home/user/project/setup.py

q = Path('~/notes.txt')
print(q.expanduser())       # /home/user/notes.txt

print(Path.home())          # /home/user

Plattformübergreifende Eigenschaften: drive, root, parts und Groß-/Kleinschreibung

Die Eigenschaft drive gibt einen Windows-Laufwerksbuchstaben oder einen UNC-Freigabestring zurück und ist auf POSIX immer leer. root gibt den führenden Slash oder Backslash zurück. parts zerlegt den Pfad in ein Tupel von Komponenten und gruppiert drive und root auf Windows zu einem einzigen Eintrag.

PureWindowsPath ignoriert Groß-/Kleinschreibung bei Gleichheits- und Vergleichsoperationen, daher ist PureWindowsPath('FOO') gleich PureWindowsPath('foo'). PurePosixPath unterscheidet zwischen Groß- und Kleinschreibung. Diese Unterscheidung ist wichtig, wenn Sie Mengen oder Dictionaries von Pfaden erstellen, die plattformübergreifend konsistent funktionieren müssen.

from pathlib import PureWindowsPath, PurePosixPath

w = PureWindowsPath('C:/Users/alice/docs')
print(w.parts)   # ('C:\\', 'Users', 'alice', 'docs')
print(w.drive)   # 'c:'
print(w.root)    # '\\'

print(PureWindowsPath('FOO') == PureWindowsPath('foo'))  # True
print(PurePosixPath('FOO') == PurePosixPath('foo'))      # False

Behandlung von Pfadfehlern: OSError, UnsupportedOperation und Plattformbeschränkungen

Methoden konkreter Pfade, die das Dateisystem berühren, lösen OSError (oder Unterklassen wie FileNotFoundError, PermissionError) aus, wenn der zugrunde liegende Systemaufruf fehlschlägt. resolve(strict=True) löst OSError für nicht existierende Pfade oder Symlink-Loops aus. Ab Python 3.13 löst PosixPath UnsupportedOperation aus, wenn es auf Windows instanziiert wird, und WindowsPath löst es auf Nicht-Windows-Plattformen aus. Zuvor wurde NotImplementedError ausgelöst.

UnsupportedOperation erbt von NotImplementedError, daher fängt das Catchen von NotImplementedError auch diese Ausnahme ab, aber eine explizite Behandlung ist klarer. Wenn Sie Code schreiben, der auf beiden Plattformen laufen muss, bevorzugen Sie Path gegenüber PosixPath oder WindowsPath, um versehentliche Instanziierungen der falschen Variante zu vermeiden.

from pathlib import Path

try:
    Path('/nonexistent').resolve(strict=True)
except OSError as exc:
    print(f'Resolution failed: {exc}')

# On Python 3.13+, this raises UnsupportedOperation on Linux:
# from pathlib import WindowsPath
# WindowsPath('C:/')

Integration von pathlib-Objekten mit os-Modulfunktionen

PurePath implementiert os.PathLike seit Python 3.6, sodass jedes pathlib-Objekt direkt an os.listdir, os.stat, os.remove, os.symlink und ähnliche Funktionen übergeben werden kann, ohne Konvertierung. Dies ermöglicht es Ihnen, pathlib-Komfort mit os-Level-Operationen zu mischen, die kein pathlib-Äquivalent haben.

os.name gibt 'posix' oder 'nt' zurück und ist die Standardmethode, um auf der Plattform zu verzweigen, wenn pathlib allein nicht genügend Informationen bereitstellt, wie etwa beim Prüfen, ob os.symlink auf Windows erhöhte Privilegien erfordert oder ob eine Funktion den dir_fd-Parameter unterstützt.

import os
from pathlib import Path

p = Path('/tmp/example')
# pathlib object works directly with os functions
os.makedirs(p, exist_ok=True)
os.remove(p / 'old.txt')

if os.name == 'nt':
    print('Windows: symlinks need Developer Mode')
else:
    print('Unix: symlinks available without elevation')