Field-Objekte

Field-Objekte beschreiben jedes definierte Feld. Diese Objekte werden intern erstellt und von der Modul-weiten Methode fields() (siehe unten) zurückgegeben. Benutzer sollten niemals direkt ein Field-Objekt instanziieren. Seine dokumentierten Attribute sind

• name: Der Name des Feldes.
• type: Der Typ des Feldes.
• default, default_factory, init, repr, hash, compare und metadata haben die identische Bedeutung und Werte wie in der Deklaration field().

Andere Attribute können existieren, aber sie sind privat und dürfen nicht inspiziert oder darauf aufgebaut werden.

Post-init-Verarbeitung

Der generierte Code für __init__ ruft eine Methode namens __post_init__ auf, falls diese in der Klasse definiert ist. Sie wird als self.__post_init__() aufgerufen. Wenn keine __init__-Methode generiert wird, wird __post_init__ nicht automatisch aufgerufen.

Dies ermöglicht unter anderem die Initialisierung von Feldwerten, die von einem oder mehreren anderen Feldern abhängen. Zum Beispiel

@dataclass
class C:
    a: float
    b: float
    c: float = field(init=False)

    def __post_init__(self):
        self.c = self.a + self.b

Siehe den Abschnitt unten über Nur-Init-Variablen für Möglichkeiten, Parameter an __post_init__() zu übergeben. Siehe auch die Warnung, wie replace() init=False-Felder behandelt.

Klassenvariablen

Ein Bereich, in dem dataclass tatsächlich den Typ eines Feldes untersucht, ist die Bestimmung, ob ein Feld eine Klassenvariable gemäß PEP 526 ist. Dies geschieht durch Überprüfung, ob der Typ des Feldes typing.ClassVar ist. Wenn ein Feld eine ClassVar ist, wird es von der Betrachtung als Feld ausgeschlossen und von den Data Class-Mechanismen ignoriert. Weitere Diskussionen finden Sie unter [8]. Solche ClassVar-Pseudo-Felder werden von der Modul-weiten Funktion fields() nicht zurückgegeben.

Nur-Init-Variablen

Der andere Bereich, in dem dataclass eine Typannotation untersucht, ist die Bestimmung, ob ein Feld eine Nur-Init-Variable ist. Dies geschieht, indem geprüft wird, ob der Typ eines Feldes vom Typ dataclasses.InitVar ist. Wenn ein Feld eine InitVar ist, wird es als Pseudo-Feld namens Init-Only Field betrachtet. Da es sich nicht um ein echtes Feld handelt, wird es von der Modul-weiten Funktion fields() nicht zurückgegeben. Init-Only Felder werden als Parameter für die generierte __init__-Methode hinzugefügt und an die optionale __post_init__-Methode übergeben. Sie werden von Data Classes ansonsten nicht verwendet.

Nehmen wir an, ein Feld wird aus einer Datenbank initialisiert, wenn bei der Erstellung der Klasse kein Wert angegeben wird

@dataclass
class C:
    i: int
    j: int = None
    database: InitVar[DatabaseType] = None

    def __post_init__(self, database):
        if self.j is None and database is not None:
            self.j = database.lookup('j')

c = C(10, database=my_database)

In diesem Fall gibt fields() Field-Objekte für i und j zurück, aber nicht für database.

Eingefrorene Instanzen

Es ist nicht möglich, echte unveränderliche Python-Objekte zu erstellen. Durch die Übergabe von frozen=True an den Decorator @dataclass können Sie jedoch Unveränderlichkeit emulieren. In diesem Fall fügt Data Classes die Methoden __setattr__ und __delattr__ zur Klasse hinzu. Diese Methoden lösen eine FrozenInstanceError aus, wenn sie aufgerufen werden.

Bei der Verwendung von frozen=True gibt es einen geringen Performance-Nachteil: __init__ kann keine einfache Zuweisung zur Initialisierung von Feldern verwenden und muss object.__setattr__ verwenden.

Vererbung

Wenn die Data Class vom Decorator @dataclass erstellt wird, durchsucht sie alle Basisklassen der Klasse in umgekehrter MRO-Reihenfolge (d.h. beginnend bei object) und fügt für jede gefundene Data Class die Felder dieser Basisklasse zu einer geordneten Zuordnung von Feldern hinzu. Nachdem alle Felder der Basisklasse hinzugefügt wurden, fügt sie ihre eigenen Felder zur geordneten Zuordnung hinzu. Alle generierten Methoden verwenden diese kombinierte, berechnete geordnete Zuordnung von Feldern. Da die Felder in der Reihenfolge ihrer Einfügung stehen, überschreiben abgeleitete Klassen Basisklassen. Ein Beispiel

@dataclass
class Base:
    x: Any = 15.0
    y: int = 0

@dataclass
class C(Base):
    z: int = 10
    x: int = 15

Die endgültige Liste der Felder ist in der Reihenfolge x, y, z. Der endgültige Typ von x ist int, wie in Klasse C angegeben.

Die generierte __init__-Methode für C sieht wie folgt aus

def __init__(self, x: int = 15, y: int = 0, z: int = 10):

Standard-Factory-Funktionen

Wenn ein Feld eine default_factory angibt, wird diese mit null Argumenten aufgerufen, wenn ein Standardwert für das Feld benötigt wird. Zum Beispiel, um eine neue Instanz einer Liste zu erstellen, verwenden Sie

l: list = field(default_factory=list)

Wenn ein Feld von __init__ ausgeschlossen wird (mit init=False) und das Feld auch eine default_factory angibt, dann wird die Default-Factory-Funktion immer aus der generierten __init__-Funktion aufgerufen. Dies geschieht, da es keine andere Möglichkeit gibt, dem Feld einen Anfangswert zu geben.

Veränderliche Standardwerte

Python speichert Standardwerte für Membervariablen in Klassenattributen. Betrachten Sie dieses Beispiel ohne Data Classes

class C:
    x = []
    def add(self, element):
        self.x += element

o1 = C()
o2 = C()
o1.add(1)
o2.add(2)
assert o1.x == [1, 2]
assert o1.x is o2.x

Beachten Sie, dass die beiden Instanzen der Klasse C dieselbe Klassenvariable x teilen, wie erwartet.

Mit Data Classes, *wenn* dieser Code gültig wäre

@dataclass
class D:
    x: List = []
    def add(self, element):
        self.x += element

würde er Code ähnlich wie diesen generieren

class D:
    x = []
    def __init__(self, x=x):
        self.x = x
    def add(self, element):
        self.x += element

assert D().x is D().x

Dies hat dasselbe Problem wie das ursprüngliche Beispiel mit Klasse C. Das heißt, zwei Instanzen der Klasse D, die keinen Wert für x bei der Erstellung einer Klasseninstanz angeben, teilen sich dieselbe Kopie von x. Da Data Classes normale Python-Klassenerstellung verwenden, teilen sie sich auch dieses Problem. Es gibt keine allgemeine Möglichkeit für Data Classes, diesen Zustand zu erkennen. Stattdessen löst Data Classes einen TypeError aus, wenn sie einen Standardparameter vom Typ list, dict oder set erkennt. Dies ist eine partielle Lösung, schützt aber vor vielen gängigen Fehlern. Weitere Einzelheiten finden Sie unter Automatische Unterstützung für veränderliche Standardwerte im Abschnitt Abgelehnte Ideen.

Die Verwendung von Default-Factory-Funktionen ist eine Möglichkeit, neue Instanzen von veränderlichen Typen als Standardwerte für Felder zu erstellen

@dataclass
class D:
    x: list = field(default_factory=list)

assert D().x is not D().x

Hilfsfunktionen auf Modulebene

• fields(class_or_instance): Gibt ein Tupel von Field-Objekten zurück, die die Felder für diese Data Class definieren. Akzeptiert entweder eine Data Class oder eine Instanz einer Data Class. Löst ValueError aus, wenn keine Data Class oder eine Instanz davon übergeben wird. Gibt keine Pseudo-Felder zurück, die ClassVar oder InitVar sind.
• asdict(instance, *, dict_factory=dict): Konvertiert die Data Class instance in ein Dict (unter Verwendung der Factory-Funktion dict_factory). Jede Data Class wird in ein Dict ihrer Felder konvertiert, als Name:Wert-Paare. Data Classes, Dicts, Listen und Tupel werden rekursiv durchlaufen. Zum Beispiel

  @dataclass
  class Point:
       x: int
       y: int
  
  @dataclass
  class C:
       l: List[Point]
  
  p = Point(10, 20)
  assert asdict(p) == {'x': 10, 'y': 20}
  
  c = C([Point(0, 0), Point(10, 4)])
  assert asdict(c) == {'l': [{'x': 0, 'y': 0}, {'x': 10, 'y': 4}]}
  

  Löst TypeError aus, wenn instance keine Data Class-Instanz ist.

• astuple(*, tuple_factory=tuple): Konvertiert die Data Class instance in ein Tupel (unter Verwendung der Factory-Funktion tuple_factory). Jede Data Class wird in ein Tupel ihrer Feldwerte konvertiert. Data Classes, Dicts, Listen und Tupel werden rekursiv durchlaufen.

  Fortsetzung des vorherigen Beispiels

  assert astuple(p) == (10, 20)
  assert astuple(c) == ([(0, 0), (10, 4)],)
  

  Löst TypeError aus, wenn instance keine Data Class-Instanz ist.

• make_dataclass(cls_name, fields, *, bases=(), namespace=None): Erstellt eine neue Data Class mit dem Namen cls_name, Feldern wie in fields definiert, Basisklassen wie in bases angegeben und initialisiert mit einem Namespace wie in namespace angegeben. fields ist ein iterierbares Element, dessen Elemente entweder name, (name, type) oder (name, type, Field) sind. Wenn nur name angegeben wird, wird typing.Any für type verwendet. Diese Funktion ist nicht unbedingt erforderlich, da jeder Python-Mechanismus zur Erstellung einer neuen Klasse mit __annotations__ dann die Funktion dataclass anwenden kann, um diese Klasse in eine Data Class zu konvertieren. Diese Funktion wird als Bequemlichkeit angeboten. Zum Beispiel

  C = make_dataclass('C',
                     [('x', int),
                       'y',
                      ('z', int, field(default=5))],
                     namespace={'add_one': lambda self: self.x + 1})
  

  Entspricht

  @dataclass
  class C:
      x: int
      y: 'typing.Any'
      z: int = 5
  
      def add_one(self):
          return self.x + 1
  

• replace(instance, **changes): Erstellt ein neues Objekt desselben Typs wie instance und ersetzt Felder durch Werte aus changes. Wenn instance keine Data Class ist, wird TypeError ausgelöst. Wenn Werte in changes keine Felder angeben, wird TypeError ausgelöst.

  Das neu zurückgegebene Objekt wird durch Aufruf der Methode __init__ der Data Class erstellt. Dies stellt sicher, dass __post_init__, falls vorhanden, ebenfalls aufgerufen wird.

  Nur für die Initialisierung vorgesehene Variablen ohne Standardwerte, falls vorhanden, müssen beim Aufruf von replace angegeben werden, damit sie an __init__ und __post_init__ übergeben werden können.

  Es ist ein Fehler, wenn changes Felder enthält, die als init=False definiert sind. In diesem Fall wird ein ValueError ausgelöst.

  Seien Sie sich bewusst, wie init=False Felder bei einem Aufruf von replace() funktionieren. Sie werden nicht vom Quellobjekt kopiert, sondern in __post_init__() initialisiert, falls sie überhaupt initialisiert werden. Es wird erwartet, dass init=False Felder selten und sparsam verwendet werden. Wenn sie verwendet werden, ist es ratsam, alternative Klassenkonstruktoren zu haben, oder vielleicht eine benutzerdefinierte Methode replace() (oder ähnlich benannt), die das Kopieren von Instanzen behandelt.

• is_dataclass(class_or_instance): Gibt True zurück, wenn der Parameter eine Data Class oder eine Instanz davon ist, andernfalls False.

  Wenn Sie wissen müssen, ob eine Klasse eine Instanz einer Data Class ist (und nicht selbst eine Data Class), fügen Sie eine weitere Prüfung für not isinstance(obj, type) hinzu.

  def is_dataclass_instance(obj):
      return is_dataclass(obj) and not isinstance(obj, type)
  

python-ideas Diskussion

Diese Diskussion begann auf python-ideas [9] und wurde in ein GitHub-Repository [10] zur weiteren Diskussion verschoben. Im Rahmen dieser Diskussion haben wir die Entscheidung getroffen, die Syntax von PEP 526 für die Erkennung von Feldern zu verwenden.

Unterstützung für die automatische Einstellung von __slots__?

Zumindest für die Erstveröffentlichung wird __slots__ nicht unterstützt. __slots__ muss zur Zeit der Klassenerstellung hinzugefügt werden. Der Data Class-Decorator wird nach der Klassenerstellung aufgerufen. Um __slots__ hinzuzufügen, müsste der Decorator eine neue Klasse erstellen, __slots__ setzen und sie zurückgeben. Da dieses Verhalten etwas überraschend ist, unterstützt die Anfangsversion von Data Classes das automatische Setzen von __slots__ nicht. Es gibt eine Reihe von Workarounds

• Fügen Sie __slots__ manuell in die Klassendefinition ein.
• Schreiben Sie eine Funktion (die als Decorator verwendet werden könnte), die die Klasse mit fields() inspiziert und eine neue Klasse mit gesetzten __slots__ erstellt.

Für weitere Diskussionen siehe [11].

Warum nicht einfach namedtuple verwenden?

• Jedes benannte Tupel kann versehentlich mit jedem anderen mit derselben Anzahl von Feldern verglichen werden. Zum Beispiel: Point3D(2017, 6, 2) == Date(2017, 6, 2). Mit Data Classes würde dies False ergeben.
• Ein benanntes Tupel kann versehentlich mit einem Tupel verglichen werden. Zum Beispiel: Point2D(1, 10) == (1, 10). Mit Data Classes würde dies False ergeben.
• Instanzen sind immer iterierbar, was das Hinzufügen von Feldern erschweren kann. Wenn eine Bibliothek definiert

  Time = namedtuple('Time', ['hour', 'minute'])
  def get_time():
      return Time(12, 0)
  

  Dann wenn ein Benutzer diesen Code wie folgt verwendet

  hour, minute = get_time()
  

  dann wäre es nicht möglich, ein second-Feld zu Time hinzuzufügen, ohne den Code des Benutzers zu brechen.

• Keine Option für mutable Instanzen.
• Kann keine Standardwerte angeben.
• Kann nicht steuern, welche Felder für __init__, __repr__ usw. verwendet werden.
• Kann die Kombination von Feldern durch Vererbung nicht unterstützen.

Warum nicht einfach typing.NamedTuple verwenden?

Für Klassen mit statisch definierten Feldern unterstützt es eine ähnliche Syntax wie Data Classes mit Typannotationen. Dies erzeugt ein benanntes Tupel, so dass es die Vorteile von namedtuple und einige seiner Nachteile teilt. Data Classes unterstützen im Gegensatz zu typing.NamedTuple die Kombination von Feldern durch Vererbung.

Warum nicht einfach attrs verwenden?

• attrs entwickelt sich schneller, als berücksichtigt werden könnte, wenn es in die Standardbibliothek aufgenommen würde.
• attrs unterstützt zusätzliche Funktionen, die hier nicht vorgeschlagen werden: Validatoren, Konverter, Metadaten usw. Data Classes treffen eine Entscheidung, um die Einfachheit zu wahren, indem sie diese Funktionen nicht implementieren.

Für weitere Diskussionen siehe [12].

Post-init-Parameter

In einer früheren Version dieser PEP, bevor InitVar hinzugefügt wurde, hat die Post-Init-Funktion __post_init__ keine Parameter erhalten.

Der normale Weg, parametrisierte Initialisierungen durchzuführen (und nicht nur mit Data Classes), ist die Bereitstellung eines alternativen Klassenmethoden-Konstruktors. Zum Beispiel

@dataclass
class C:
    x: int

    @classmethod
    def from_file(cls, filename):
        with open(filename) as fl:
            file_value = int(fl.read())
        return C(file_value)

c = C.from_file('file.txt')

Da die Funktion __post_init__ das Letzte ist, was im generierten __init__ aufgerufen wird, ist ein Klassenmethoden-Konstruktor (der auch Code unmittelbar nach der Objekterstellung ausführen kann) funktional äquivalent dazu, Parameter an eine __post_init__-Funktion übergeben zu können.

Mit InitVars können __post_init__-Funktionen nun Parameter erhalten. Sie werden zuerst an __init__ übergeben, das sie an __post_init__ weiterleitet, wo der Benutzer-Code sie nach Bedarf verwenden kann.

Der einzige wirkliche Unterschied zwischen alternativen Klassenmethoden-Konstruktoren und InitVar-Pseudo-Feldern liegt in Bezug auf erforderliche Nicht-Feld-Parameter während der Objekterstellung. Mit InitVars müssen bei der Verwendung von __init__ und der Modul-weiten Funktion replace() InitVars immer angegeben werden. Betrachten Sie den Fall, dass ein context-Objekt zur Erstellung einer Instanz benötigt wird, aber nicht als Feld gespeichert wird. Mit alternativen Klassenmethoden-Konstruktoren ist der context-Parameter immer optional, da Sie das Objekt immer noch erstellen könnten, indem Sie __init__ durchlaufen (es sei denn, Sie unterdrücken dessen Erstellung). Welcher Ansatz besser geeignet ist, hängt von der Anwendung ab, aber beide Ansätze werden unterstützt.

Ein weiterer Grund für die Verwendung von InitVar-Feldern ist, dass der Klassenautor die Reihenfolge der __init__-Parameter steuern kann. Dies ist besonders wichtig bei regulären Feldern und InitVar-Feldern mit Standardwerten, da alle Felder mit Standardwerten nach allen Feldern ohne Standardwerte kommen müssen. Ein früheres Design sah vor, dass alle Init-Only-Felder nach den regulären Feldern kamen. Das bedeutete, dass, wenn irgendein Feld einen Standardwert hatte, alle Init-Only-Felder ebenfalls Standardwerte haben mussten.

Namen der Funktionen asdict und astuple

Die Namen der Modul-weiten Hilfsfunktionen asdict() und astuple() sind wohl nicht PEP 8-konform und sollten as_dict() bzw. as_tuple() sein. Nach Diskussionen [13] wurde jedoch beschlossen, die Konsistenz mit namedtuple._asdict() und attr.asdict() beizubehalten.

Kopieren von init=False-Feldern nach der Erstellung eines neuen Objekts in replace()

Felder, die init=False sind, werden per Definition nicht an __init__ übergeben, sondern stattdessen mit einem Standardwert initialisiert, oder durch Aufruf einer Standard-Factory-Funktion in __init__, oder durch Code in __post_init__.

Eine frühere Version dieser PEP gab vor, dass init=False Felder vom Quellobjekt auf das neu erstellte Objekt kopiert würden, nachdem __init__ zurückgekehrt war, aber das wurde als inkonsistent mit der Verwendung von __init__ und __post_init__ zur Initialisierung des neuen Objekts angesehen. Zum Beispiel betrachten wir diesen Fall

@dataclass
class Square:
    length: float
    area: float = field(init=False, default=0.0)

    def __post_init__(self):
        self.area = self.length * self.length

s1 = Square(1.0)
s2 = replace(s1, length=2.0)

Wenn init=False Felder vom Quell- auf das Zielobjekt kopiert würden, nachdem __post_init__ ausgeführt wurde, dann wäre s2 Square(length=2.0, area=1.0), anstatt des korrekten Square(length=2.0, area=4.0).

Automatische Unterstützung für veränderliche Standardwerte

Ein Vorschlag war, Standardwerte automatisch zu kopieren, so dass, wenn eine literale Liste [] ein Standardwert wäre, jede Instanz eine neue Liste erhalten würde. Es gab unerwünschte Nebenwirkungen dieser Entscheidung, so dass die endgültige Entscheidung ist, die 3 bekannten eingebauten veränderlichen Typen zu verbieten: Liste, Dict und Set. Für eine vollständige Diskussion dieser und anderer Optionen siehe [14].

Benutzerdefinierte __init__-Methode

Manchmal reicht die generierte Methode __init__ nicht aus. Zum Beispiel, wenn Sie ein Objekt haben möchten, das *args und **kwargs speichert

@dataclass(init=False)
class ArgHolder:
    args: List[Any]
    kwargs: Mapping[Any, Any]

    def __init__(self, *args, **kwargs):
        self.args = args
        self.kwargs = kwargs

a = ArgHolder(1, 2, three=3)

Ein kompliziertes Beispiel

Dieser Code existiert in einem Closed-Source-Projekt

class Application:
    def __init__(self, name, requirements, constraints=None, path='', executable_links=None, executables_dir=()):
        self.name = name
        self.requirements = requirements
        self.constraints = {} if constraints is None else constraints
        self.path = path
        self.executable_links = [] if executable_links is None else executable_links
        self.executables_dir = executables_dir
        self.additional_items = []

    def __repr__(self):
        return f'Application({self.name!r},{self.requirements!r},{self.constraints!r},{self.path!r},{self.executable_links!r},{self.executables_dir!r},{self.additional_items!r})'

Dies kann ersetzt werden durch

@dataclass
class Application:
    name: str
    requirements: List[Requirement]
    constraints: Dict[str, str] = field(default_factory=dict)
    path: str = ''
    executable_links: List[str] = field(default_factory=list)
    executable_dir: Tuple[str] = ()
    additional_items: List[str] = field(init=False, default_factory=list)

Die Data Class-Version ist deklarativer, hat weniger Code, unterstützt typing und enthält die anderen generierten Funktionen.