os.scandir()

Insbesondere schlägt diese PEP vor, der os-Modul in der Standardbibliothek eine einzelne Funktion, scandir, hinzuzufügen, die ein einzelnes, optionales String-Argument annimmt.

scandir(path='.') -> generator of DirEntry objects

Wie listdir ruft scandir die Verzeichnisiterationssystemaufrufe des Betriebssystems auf, um die Namen der Dateien im angegebenen path zu erhalten, aber es unterscheidet sich in zwei Punkten von listdir:

• Anstatt reine Dateinamen-Strings zurückzugeben, gibt es leichte DirEntry-Objekte zurück, die den Dateinamen-String enthalten und einfache Methoden bereitstellen, die den Zugriff auf zusätzliche Daten ermöglichen, die das Betriebssystem möglicherweise zurückgegeben hat.
• Es gibt einen Generator zurück anstelle einer Liste, so dass scandir als echter Iterator fungiert, anstatt die vollständige Liste sofort zurückzugeben.

scandir() liefert ein DirEntry-Objekt für jede Datei und jedes Unterverzeichnis in path. Genau wie listdir werden die Pseudo-Verzeichnisse '.' und '..' übersprungen, und die Einträge werden in systemabhängiger Reihenfolge geliefert. Jedes DirEntry-Objekt hat die folgenden Attribute und Methoden:

• name: Der Dateiname des Eintrags, relativ zum scandir-Argument path (entspricht den Rückgabewerten von os.listdir).
• path: Der vollständige Pfadname des Eintrags (nicht unbedingt ein absoluter Pfad) – das Äquivalent von os.path.join(scandir_path, entry.name).
• inode(): Gibt die Inode-Nummer des Eintrags zurück. Das Ergebnis wird im DirEntry-Objekt zwischengespeichert. Verwenden Sie os.stat(entry.path, follow_symlinks=False).st_ino, um aktuelle Informationen abzurufen. Unter Unix ist kein Systemaufruf erforderlich.
• is_dir(*, follow_symlinks=True): Ähnlich wie pathlib.Path.is_dir(), aber der Rückgabewert wird im DirEntry-Objekt zwischengespeichert; erfordert in den meisten Fällen keinen Systemaufruf; folgt symbolischen Links nicht, wenn follow_symlinks False ist.
• is_file(*, follow_symlinks=True): Ähnlich wie pathlib.Path.is_file(), aber der Rückgabewert wird im DirEntry-Objekt zwischengespeichert; erfordert in den meisten Fällen keinen Systemaufruf; folgt symbolischen Links nicht, wenn follow_symlinks False ist.
• is_symlink(): Ähnlich wie pathlib.Path.is_symlink(), aber der Rückgabewert wird im DirEntry-Objekt zwischengespeichert; erfordert in den meisten Fällen keinen Systemaufruf.
• stat(*, follow_symlinks=True): Wie os.stat(), aber der Rückgabewert wird im DirEntry-Objekt zwischengespeichert; erfordert unter Windows keinen Systemaufruf (außer für Symlinks); folgt symbolischen Links nicht (wie os.lstat()), wenn follow_symlinks False ist.

Alle *Methoden* können in einigen Fällen Systemaufrufe ausführen und daher möglicherweise OSError auslösen – siehe Abschnitt „Hinweise zur Fehlerbehandlung“ für weitere Details.

Die Namen der DirEntry-Attribute und -Methoden wurden, wo immer möglich, den Namen im neuen pathlib-Modul angepasst, um die Konsistenz zu gewährleisten. Der einzige Funktionsunterschied besteht darin, dass die DirEntry-Methoden ihre Werte nach dem ersten Aufruf im Entry-Objekt zwischenspeichern.

Wie die anderen Funktionen im os-Modul akzeptiert scandir() entweder ein Bytes- oder ein String-Objekt für den Parameter path und gibt die Attribute DirEntry.name und DirEntry.path mit demselben Typ wie path zurück. Es wird jedoch *dringend empfohlen*, den String-Typ zu verwenden, da dies die plattformübergreifende Unterstützung für Unicode-Dateinamen gewährleistet. (Unter Windows sind Bytes-Dateinamen seit Python 3.3 veraltet.)

os.walk()

Als Teil dieses Vorschlags wird os.walk() ebenfalls so modifiziert, dass scandir() anstelle von listdir() und os.path.isdir() verwendet wird. Dies wird die Geschwindigkeit von os.walk() erheblich erhöhen (wie oben erwähnt, um das 2- bis 20-fache, abhängig vom System).

Hinweise zur Zwischenspeicherung

Die DirEntry-Objekte sind relativ einfach – die Attribute name und path sind offensichtlich immer zwischengespeichert, und die Methoden is_X und stat speichern ihre Werte (sofort unter Windows über FindNextFile und beim ersten Gebrauch unter POSIX-Systemen über einen stat-Systemaufruf) und rufen sie nie wieder vom System ab.

Aus diesem Grund sind DirEntry-Objekte dazu bestimmt, verwendet und nach der Iteration verworfen zu werden, nicht in langzeitigen Datenstrukturen gespeichert und die Methoden immer wieder aufgerufen zu werden.

Wenn Entwickler ein „Aktualisierungsverhalten“ wünschen (z. B. um die Größe einer Datei zu überwachen), können sie einfach pathlib.Path-Objekte verwenden oder die regulären Funktionen os.stat() oder os.path.getsize() aufrufen, die bei jedem Aufruf frische Daten vom Betriebssystem abrufen.

Hinweise zur Fehlerbehandlung

DirEntry.is_X() und DirEntry.stat() sind explizit Methoden und keine Attribute oder Eigenschaften, um zu verdeutlichen, dass sie keine günstigen Operationen sein müssen (obwohl sie es oft sind) und dass sie einen Systemaufruf durchführen können. Infolgedessen können diese Methoden OSError auslösen.

Zum Beispiel führt DirEntry.stat() unter POSIX-basierten Systemen immer einen Systemaufruf durch, und die Methoden DirEntry.is_X() führen unter solchen Systemen einen stat()-Systemaufruf aus, wenn readdir() d_type nicht unterstützt oder einen d_type mit dem Wert DT_UNKNOWN zurückgibt, was unter bestimmten Bedingungen oder auf bestimmten Dateisystemen auftreten kann.

Oft spielt das keine Rolle – zum Beispiel fängt os.walk(), wie in der Standardbibliothek definiert, nur Fehler bei den listdir()-Aufrufen ab.

Außerdem, da das Ausnahmeverhalten der Methoden DirEntry.is_X dem von pathlib entspricht – das nur im Falle von Berechtigungen oder anderen fatalen Fehlern OSError auslöst, aber False zurückgibt, wenn der Pfad nicht existiert oder ein defekter Symlink ist –, ist es oft nicht notwendig, Fehler bei den is_X()-Aufrufen abzufangen.

Wenn ein Benutzer jedoch eine feingranulare Fehlerbehandlung benötigt, kann es wünschenswert sein, OSError um alle Methodenaufrufe abzufangen und entsprechend zu behandeln.

Unten finden Sie beispielsweise eine Version des oben gezeigten get_tree_size()-Beispiels, jedoch mit hinzugefügter feingranularer Fehlerbehandlung.

def get_tree_size(path):
    """Return total size of files in path and subdirs. If
    is_dir() or stat() fails, print an error message to stderr
    and assume zero size (for example, file has been deleted).
    """
    total = 0
    for entry in os.scandir(path):
        try:
            is_dir = entry.is_dir(follow_symlinks=False)
        except OSError as error:
            print('Error calling is_dir():', error, file=sys.stderr)
            continue
        if is_dir:
            total += get_tree_size(entry.path)
        else:
            try:
                total += entry.stat(follow_symlinks=False).st_size
            except OSError as error:
                print('Error calling stat():', error, file=sys.stderr)
    return total

Benennung

Der einzige andere wirkliche Anwärter für den Namen dieser Funktion war iterdir(). Funktionen vom Typ iterX() in Python (hauptsächlich in Python 2 zu finden) sind jedoch tendenziell einfache Iterator-Äquivalente ihrer Nicht-Iterator-Gegenstücke. Zum Beispiel ist dict.iterkeys() nur eine Iteratorversion von dict.keys(), aber die zurückgegebenen Objekte sind identisch. Im Fall von scandir() sind die Rückgabewerte jedoch ganz andere Objekte (DirEntry-Objekte im Gegensatz zu Dateinamen-Strings), daher sollte dies wahrscheinlich durch eine Namensänderung widergespiegelt werden – daher scandir().

Siehe einige **relevante Diskussionen auf python-dev**.

Wildcard-Unterstützung

FindFirstFile/FindNextFile unter Windows unterstützt die Übergabe eines „Wildcards“ wie *.jpg. Daher hielten es zuerst einige Leute (einschließlich des Autors dieser PEP) für eine gute Idee, ein Schlüsselwortargument windows_wildcard für die Funktion scandir einzuführen, damit Benutzer dies übergeben können.

Nach weiterer Überlegung und Diskussion wurde jedoch entschieden, dass dies eine schlechte Idee wäre, *es sei denn, es könnte plattformübergreifend umgesetzt werden* (ein Schlüsselwortargument pattern oder Ähnliches). Dies scheint zunächst einfach genug zu sein – verwenden Sie einfach die OS-Wildcard-Unterstützung unter Windows und etwas wie fnmatch oder re anschließend unter POSIX-Systemen.

Leider sind die genauen Windows-Wildcard-Matching-Regeln von Microsoft nirgends dokumentiert und sie sind ziemlich eigenartig (siehe diesen **Blogbeitrag**), was es sehr problematisch macht, sie mit fnmatch oder Regexes zu emulieren.

Daher war der Konsens, dass die Windows-Wildcard-Unterstützung eine schlechte Idee war. Sie könnte zu einem späteren Zeitpunkt hinzugefügt werden, wenn es einen plattformübergreifenden Weg gibt, sie zu erreichen, aber nicht für die Erstversion.

Lesen Sie mehr in diesem **Nov 2012 python-ideas-Thread** und diesem **Juni 2014 python-dev-Thread zu PEP 471**.

Methoden, die Symlinks nicht standardmäßig folgen

Es gab viel Debatte auf python-dev (siehe Nachrichten in **diesem Thread**) darüber, ob die DirEntry-Methoden symbolische Links folgen sollten oder nicht (als die is_X()-Methoden keinen Parameter follow_symlinks hatten).

Anfangs taten sie dies nicht (siehe frühere Versionen dieser PEP und das scandir.py-Modul), aber Victor Stinner argumentierte überzeugend auf python-dev, dass das standardmäßige Folgen von Links eine bessere Idee sei, weil

• das Folgen von Links normalerweise das ist, was man will (in 92 % der Fälle in der Standardbibliothek folgen Funktionen, die os.listdir() und os.path.isdir() verwenden, Symlinks)
• das ist der Präzedenzfall, der von den ähnlichen Funktionen os.path.isdir() und pathlib.Path.is_dir() gesetzt wird, also wäre es verwirrend, anders zu handeln.
• mit dem Ansatz, der Links nicht folgt, müssten Sie, wenn Sie Links folgen wollten, etwas wie if (entry.is_symlink() and os.path.isdir(entry.path)) or entry.is_dir() sagen, was umständlich ist.

Als Beispiel, das zeigt, dass die Version ohne Symlink-Folge fehleranfällig ist, hatte der Autor dieser PEP einen Fehler, der durch die falsche Auswertung dieses genauen Tests in seiner anfänglichen Implementierung von scandir.walk() in scandir.py verursacht wurde (siehe **Issue #4 hier**).

Am Ende gab es keine vollständige Einigung darüber, dass die Methoden Symlinks folgen sollten, aber es gab einen grundlegenden Konsens unter den am stärksten beteiligten Teilnehmern, und der Autor dieser PEP glaubt, dass der obige Fall stark genug ist, um das Standardverhalten des Folgen von Symlinks zu rechtfertigen.

Darüber hinaus ist es einfach, die relevanten Methoden mit follow_symlinks=False aufzurufen, wenn das andere Verhalten gewünscht wird.

DirEntry-Attribute als Eigenschaften

In gewisser Weise wäre es schöner, wenn die DirEntry is_X() und stat() Eigenschaften anstelle von Methoden wären, um anzuzeigen, dass sie sehr günstig oder kostenlos sind. Dies ist jedoch nicht ganz der Fall, da stat() unter POSIX-basierten Systemen einen OS-Aufruf erfordert, unter Windows jedoch nicht. Selbst is_dir() und ähnliche können unter POSIX-basierten Systemen einen OS-Aufruf ausführen, wenn der dirent.d_type-Wert DT_UNKNOWN ist (auf bestimmten Dateisystemen).

Außerdem würden die Leute erwarten, dass der Attributzugriff entry.is_dir nur AttributeError auslöst, nicht OSError im Fall, dass er im Hintergrund einen Systemaufruf tätigt. Aufrufender Code müsste einen try/except um das haben, was wie ein einfacher Attributzugriff aussieht, und daher ist es viel besser, sie zu *Methoden* zu machen.

Siehe **diesen May 2013 python-dev-Thread**, in dem der Autor dieser PEP dies darlegt und eine Zustimmung von Kernentwicklern erhält.

DirEntry-Felder als „statische“ Attribute

In **dieser Juli 2014 python-dev-Nachricht** schlug Paul Moore eine Lösung vor, die ein „dünner Wrapper um das Betriebssystemmerkmal“ war, bei dem das DirEntry-Objekt nur statische Attribute hatte: name, path und is_X, wobei die st_X-Attribute nur unter Windows vorhanden waren. Die Idee war, diese einfachere, Low-Level-Funktion als Baustein für High-Level-Funktionen zu verwenden.

Anfangs stimmten die meisten zu, dass eine solche Vereinfachung gut sei. Es gab jedoch zwei Probleme mit diesem Ansatz. Erstens geht man davon aus, dass is_dir und ähnliche Attribute unter POSIX immer vorhanden sind, was nicht der Fall ist (wenn d_type nicht vorhanden ist oder DT_UNKNOWN ist). Zweitens ist es in der Praxis eine viel schwieriger zu bedienende API, da selbst die Attribute is_dir unter POSIX nicht immer vorhanden sind und mit hasattr() getestet und dann os.stat() aufgerufen werden müssten, wenn sie nicht vorhanden wären.

Siehe **diese Juli 2014 python-dev-Antwort** vom Autor dieser PEP, die detailliert beschreibt, warum diese Option keine ideale Lösung ist, und die anschließende Antwort von Paul Moore, der zustimmt.

DirEntry-Felder als statisch mit einer ensure_lstat-Option

Eine weitere scheinbar einfachere und attraktivere Option wurde von Alyssa Coghlan in dieser **Juni 2014 python-dev-Nachricht** vorgeschlagen: Machen Sie DirEntry.is_X und DirEntry.lstat_result zu Eigenschaften und füllen Sie DirEntry.lstat_result während der Iteration, aber nur, wenn das neue Argument ensure_lstat=True beim Aufruf von scandir() angegeben wurde.

Dies hat den Vorteil gegenüber dem oben genannten, dass Sie das Stat-Ergebnis leicht von scandir() erhalten können, wenn Sie es benötigen. Es hat jedoch den erheblichen Nachteil, dass die feingranulare Fehlerbehandlung unübersichtlich ist, da stat() während der Iteration aufgerufen wird (und somit möglicherweise OSError auslöst), was zu einer ziemlich hässlichen, handgemachten Iterationsschleife führt.

it = os.scandir(path)
while True:
    try:
        entry = next(it)
    except OSError as error:
        handle_error(path, error)
    except StopIteration:
        break

Oder es bedeutet, dass scandir() ein Argument onerror akzeptieren müsste – eine Funktion, die aufgerufen wird, wenn stat()-Fehler während der Iteration auftreten. Dies scheint dem Autor dieser PEP weder so direkt noch so Python-isch wie ein try/except-Block um einen DirEntry.stat()-Aufruf zu sein.

Ein weiterer Nachteil ist, dass os.scandir() zur Beschleunigung des Codes geschrieben ist. Das ständige Aufrufen von os.lstat() unter POSIX würde keine Geschwindigkeitssteigerung bringen. In den meisten Fällen benötigen Sie nicht das vollständige stat_result-Objekt – die Methoden is_X() sind ausreichend, und diese Informationen sind bereits bekannt.

Siehe **Ben Hoyts Juli 2014er Antwort** auf die Diskussion, die dies zusammenfasst und detailliert beschreibt, warum er den ursprünglichen Vorschlag von **PEP 471** doch „den richtigen“ hält.

Rückgabewerte als (Name, stat_result) Zwei-Tupel

Anfänglich schlug der Autor dieser PEP dieses Konzept als Funktion namens iterdir_stat() vor, die Zwei-Tupel von (name, stat_result) lieferte. Dies hat den Vorteil, dass keine neuen Typen eingeführt werden. Allerdings ist das stat_result unter POSIX-basierten Systemen nur teilweise gefüllt (die meisten Felder sind auf None gesetzt und es gibt andere Eigenheiten), sodass es sich nicht wirklich um stat_result-Objekte handelt, und dies müsste als anders als os.stat() gründlich dokumentiert werden.

Python unterstützt ordnungsgemäße Objekte mit Attributen und Methoden gut, was zu einer gesünderen und einfacheren API als bei Zwei-Tupeln führt. Außerdem macht es die DirEntry-Objekte erweiterbarer und zukunftssicherer, da Betriebssysteme Funktionalität hinzufügen und wir diese in DirEntry aufnehmen möchten.

Siehe auch einige frühere Diskussionen

• Diskussion im Mai 2013 auf python-dev, in der Alyssa Coghlan die ursprüngliche Argumentation für ein DirEntry-ähnliches Objekt vorbringt.
• Diskussion im Juni 2014 auf python-dev, in der Alyssa Coghlan (erneut) gute Argumente gegen den Zwei-Tupel-Ansatz vorbringt.

Rückgabewerte als überladene stat_result-Objekte

Eine weitere diskutierte Alternative war, die Rückgabewerte als überladene stat_result-Objekte mit den Attributen name und path zu gestalten. Abgesehen davon, dass dies eine seltsame (und angestrengte!) Art der Überladung ist, hat dies die gleichen oben genannten Probleme – die meisten stat_result-Informationen werden auf POSIX-Systemen nicht von readdir() abgerufen, nur (ein Teil) des st_mode-Werts.

Rückgabewerte als pathlib.Path-Objekte

Mit Antoine Pitrous neuem Standardbibliothekmodul pathlib scheint es auf den ersten Blick eine großartige Idee zu sein, dass scandir() Instanzen von pathlib.Path zurückgibt. Die is_X() und stat() Funktionen von pathlib.Path sind jedoch explizit nicht zwischengespeichert, während scandir sie bauartbedingt zwischenspeichern muss, da es (oft) Werte aus dem ursprünglichen Systemaufruf zur Verzeichnisiteration zurückgibt.

Und wenn die von scandir zurückgegebenen pathlib.Path-Instanzen Stat-Werte zwischenspeichern würden, die normalen pathlib.Path-Objekte aber explizit nicht, wäre das mehr als ein wenig verwirrend.

Guido van Rossum lehnte das Zwischenspeichern von Stat-Werten durch pathlib.Path im Kontext von scandir hier ausdrücklich ab, was pathlib.Path-Objekte zu einer schlechten Wahl für scandir-Rückgabewerte macht.