Protokoll

Die folgende abstrakte Basisklasse definiert das Protokoll, damit ein Objekt als Pfadobjekt betrachtet werden kann

import abc
import typing as t


class PathLike(abc.ABC):

    """Abstract base class for implementing the file system path protocol."""

    @abc.abstractmethod
    def __fspath__(self) -> t.Union[str, bytes]:
        """Return the file system path representation of the object."""
        raise NotImplementedError

Objekte, die Dateisystempfade darstellen, werden die Methode __fspath__() implementieren, die die str- oder bytes-Darstellung des Pfades zurückgibt. Die str-Darstellung ist die bevorzugte Low-Level-Pfad-Darstellung, da sie menschenlesbar ist und was Leute historisch als Pfade darstellen.

Änderungen an der Standardbibliothek

Es wird erwartet, dass die meisten APIs in Pythons Standardbibliothek, die derzeit einen Dateisystempfad akzeptieren, entsprechend aktualisiert werden, um Pfadobjekte zu akzeptieren (ob dies Code oder einfach eine Aktualisierung der Dokumentation erfordert, wird variieren). Die unten genannten Module verdienen jedoch spezifische Details, da sie entweder grundlegende Änderungen aufweisen, die die Nutzung von Pfadobjekten ermöglichen, oder Ergänzungen/Entfernungen von APIs beinhalten.

import typing as t


def fspath(path: t.Union[PathLike, str, bytes]) -> t.Union[str, bytes]:
    """Return the string representation of the path.

    If str or bytes is passed in, it is returned unchanged. If __fspath__()
    returns something other than str or bytes then TypeError is raised. If
    this function is given something that is not str, bytes, or os.PathLike
    then TypeError is raised.
    """
    if isinstance(path, (str, bytes)):
        return path

    # Work from the object's type to match method resolution of other magic
    # methods.
    path_type = type(path)
    try:
        path = path_type.__fspath__(path)
    except AttributeError:
        if hasattr(path_type, '__fspath__'):
            raise
    else:
        if isinstance(path, (str, bytes)):
            return path
        else:
            raise TypeError("expected __fspath__() to return str or bytes, "
                            "not " + type(path).__name__)

    raise TypeError("expected str, bytes or os.PathLike object, not "
                    + path_type.__name__)

/*
    Return the file system path representation of the object.

    If the object is str or bytes, then allow it to pass through with
    an incremented refcount. If the object defines __fspath__(), then
    return the result of that method. All other types raise a TypeError.
*/
PyObject *
PyOS_FSPath(PyObject *path)
{
    _Py_IDENTIFIER(__fspath__);
    PyObject *func = NULL;
    PyObject *path_repr = NULL;

    if (PyUnicode_Check(path) || PyBytes_Check(path)) {
        Py_INCREF(path);
        return path;
    }

    func = _PyObject_LookupSpecial(path, &PyId___fspath__);
    if (NULL == func) {
        return PyErr_Format(PyExc_TypeError,
                            "expected str, bytes or os.PathLike object, "
                            "not %S",
                            path->ob_type);
    }

    path_repr = PyObject_CallFunctionObjArgs(func, NULL);
    Py_DECREF(func);
    if (!PyUnicode_Check(path_repr) && !PyBytes_Check(path_repr)) {
        Py_DECREF(path_repr);
        return PyErr_Format(PyExc_TypeError,
                            "expected __fspath__() to return str or bytes, "
                            "not %S",
                            path_repr->ob_type);
    }

    return path_repr;
}

Andere Namen für die Methode des Protokolls

Verschiedene Namen wurden während der Diskussionen, die zu dieser PEP führten, vorgeschlagen, darunter __path__, __pathname__ und __fspathname__. Am Ende schien man sich auf __fspath__ zu einigen, da es eindeutig, aber nicht unnötig lang ist.

Separate str/bytes-Methoden

Zu einem Zeitpunkt wurde vorgeschlagen, dass __fspath__() nur Strings zurückgeben und eine andere Methode namens __fspathb__() eingeführt werden sollte, um Bytes zurückzugeben. Die Idee dahinter ist, dass durch die Nicht-Polymorphie von __fspath__() die Handhabung potenzieller String- oder Byte-Darstellungen einfacher werden könnte. Die allgemeine Übereinkunft war jedoch, dass die Rückgabe von Bytes eher selten sein wird und dass die verschiedenen Funktionen im `os`-Modul die bessere Abstraktion darstellen, um direkte Aufrufe von __fspath__() zu fördern.

Bereitstellung eines path-Attributs

Um das Problem zu lösen, dass pathlib.PurePath nicht von str erbt, wurde ursprünglich vorgeschlagen, ein path-Attribut einzuführen, um zu spiegeln, was os.DirEntry bietet. Letztendlich wurde jedoch festgestellt, dass ein Protokoll dasselbe Ergebnis liefern würde, ohne direkt eine API offenzulegen, mit der die meisten Leute nie direkt interagieren müssen.

Nur Strings von __fspath__() zurückgeben lassen

Ein Großteil der Diskussionen, die zu dieser PEP führten, drehte sich darum, ob __fspath__() polymorph sein und bytes sowie str zurückgeben sollte oder nur str. Die allgemeine Stimmung dafür war, dass bytes aufgrund ihres inhärenten Mangels an Informationen über ihre Kodierung schwierig zu handhaben sind, und PEP 383 ermöglicht es, alle Dateisystempfade mit str unter Verwendung des surrogateescape-Handlers darzustellen. Daher wäre es besser, die Verwendung von str als Low-Level-Pfad-Darstellung für High-Level-Pfadobjekte zu erzwingen.

Schließlich wurde entschieden, dass die Verwendung von bytes zur Darstellung von Pfaden einfach nicht verschwinden wird und daher bis zu einem gewissen Grad unterstützt werden sollte. Die Hoffnung ist, dass sich die Leute für Pfadobjekte wie `pathlib` entscheiden werden und dies die Leute von der direkten Arbeit mit bytes wegführen wird.

Ein generischer String-Encoding-Mechanismus

Zu einem Zeitpunkt gab es eine Diskussion über die Entwicklung eines generischen Mechanismus zur Extraktion einer String-Darstellung eines Objekts, die eine semantische Bedeutung hat (__str__() gibt nicht unbedingt etwas von semantischer Bedeutung zurück, das über das hinausgeht, was für das Debugging nützlich sein mag). Letztendlich wurde dies als mangelndes motivierendes Bedürfnis über das hinaus, das diese PEP auf spezifische Weise zu lösen versucht, angesehen.

__fspath__ als Attribut

Es wurde kurz erwogen, __fspath__ als Attribut statt als Methode zu implementieren. Dies wurde aus zwei Gründen abgelehnt. Erstens wurden Protokolle historisch als „magische Methoden“ und nicht als „magische Methoden und Attribute“ implementiert. Zweitens gibt es keine Garantie, dass die Low-Level-Darstellung eines Pfadobjekts vorab berechnet wird, was die Benutzer potenziell irreführen könnte, dass keine teure Berechnung im Hintergrund stattfindet, falls das Attribut als Property implementiert wäre.

Dies knüpft auch indirekt an die Idee an, ein path-Attribut einzuführen, um dasselbe zu erreichen. Diese Idee hat jedoch ein zusätzliches Problem, nämlich dass versehentlich jedes Objekt mit einem path-Attribut dem Protokoll-Duck-Typing entspricht. Die Einführung einer neuen magischen Methode für das Protokoll hilft, ein versehentliches Opt-in in das Protokoll zu vermeiden.

Spezifische Typ-Hinting-Unterstützung bereitstellen

Es gab einige Überlegungen, eine generische typing.PathLike-Klasse bereitzustellen, die z. B. typing.PathLike[str] zur Angabe eines Typ-Hints für ein Pfadobjekt ermöglicht, das eine String-Darstellung zurückgibt. Obwohl potenziell nützlich, wurde der Nutzen als zu gering eingeschätzt, um die Typ-Hint-Klasse hinzuzufügen.

Dies beseitigte auch jeden Wunsch, eine Klasse im typing-Modul einzuführen, die die Vereinigung aller akzeptablen pfaderstellenden Typen darstellt, da dies leicht durch typing.Union[str, bytes, os.PathLike] dargestellt werden kann, und die Hoffnung ist, dass Benutzer sich langsam nur an Pfadobjekte gewöhnen werden.

Bereitstellung von os.fspathb()

Es wurde vorgeschlagen, dass, um die Struktur von z. B. os.getcwd()/os.getcwdb() zu spiegeln, os.fspath() nur str zurückgeben und eine andere Funktion namens os.fspathb() eingeführt werden sollte, die nur bytes zurückgibt. Dies wurde abgelehnt, da die Zwecke der *b()-Funktionen an die Abfrage des Dateisystems gebunden sind, wo die Notwendigkeit besteht, die rohen Bytes zurückzubekommen. Da diese PEP nicht direkt mit Daten auf einem Dateisystem arbeitet (aber potenziell könnte), wurde die Ansicht vertreten, dass diese Unterscheidung unnötig ist. Es wird auch angenommen, dass der Bedarf an reinen Bytes nicht häufig genug sein wird, um ihn auf so spezifische Weise wie os.fsencode() unterstützen zu müssen, da diese ähnliche Funktionalität bietet.

__fspath__() vom Instanz aufrufen lassen

Ein früherer Entwurf dieser PEP hatte os.fspath(), der path.__fspath__() anstelle von type(path).__fspath__(path) aufruft. Die Änderung erfolgte, um mit der Auflösung anderer magischer Methoden in Python konsistent zu sein.