Improve documentation on `dataclass` inheritance

Documentation

I feel like the docs on inheritance for dataclasses could be more explicit about certain behaviors relating to dataclass inheritance.

Inheritance without the dataclass decorator

Consider

@dataclass
class A:
    foo: str

@dataclass
class B:
    bar: int

@dataclass
class C(A, B):
    pass

class D(A, B):
    pass

The docs discuss inheritance for the case

When the dataclass is being created by the @dataclass decorator

but I don't think it's necessarily obvious what happens when you inherit a dataclass without decorating the subclass, i.e. class C will inherit fields from both A and B (because it's decorated as a dataclass), but class D will only inherit fields from A.

>>> C.__init__
<function __main__.C.__init__(self, bar: int, foo: str) -> None>
>>> D.__init__
<function __main__.A.__init__(self, foo: str) -> None>

Yes, it makes sense that because D doesn't specify an __init__ method it just inherits its __init__ from the first base class that has one, but I don't think it's unreasonable to have wondered if the "dataclass-like behavior" of inheriting all fields in the MRO is part of the behaviour passed on through inheriting a dataclass. You obviously expect a subclass to inherit all methods and parameters of all its parent classes, so that not applying to dataclass fields unless you use a decorator is perhaps unexpected. Especially as is_dataclass(D) == True. Perhaps the docs could explicitly specify that if you want to inherit fields from multiple dataclass then you must decorate the subclass?

Inheritance of fields from dataclasses deeper in the MRO that the immediate (non dataclass) base class doesn't have

Consider:

@dataclass
class E(D):
    pass

Given the explanation of how the MRO is searched for dataclass fields it makes sense that E does inherit fields from both A and B, even though D has only inherited from A:

>>> E.__init__
<function __main__.E.__init__(self, bar: int, foo: str) -> None>

but it feels unintuitive that by inheriting from D you get things that D itself doesn't have. I almost wonder if this counts as a design flaw - but failing that, I suggest the docs make it explicit that you can't tell just from the __dataclass_fields__ dict of a class that you're inherting what the dataclass fields of your subclass will be (in this case D.__dataclass_fields__ contains only foo), but that you need to search the entire MRO.

The dataclass decorator's arguments effects on inherited fields

Consider the following

@dataclass(kw_only=True)
class F(A):
    baz: float

The docs specify:

kw_only: If true (the default value is False), then all fields will be marked as keyword-only

so I think you'd be forgiven for wondering if all fields of F, including fields inhertied from A, would be made keyword-only. It seems only those defined in the body of F itself are made keyword-only:

>>> F.__init__
<function __main__.F.__init__(self, foo: str, *, baz: float) -> None>

I'd like to suggest making it explicit how the arguments of the dataclass decorator affect (or not) inherited fields.

Incompatability of inheriting where default arguments are defined in more than one class

Consider:

@dataclass
class G:
    foo: int
    bar: int = 1

@dataclass
class H(G):
    spam: str
    egg: str = 'chips'

The above will throw the following exception:

TypeError: non-default argument 'spam' follows default argument 'bar'

This is mentioned briefly in the documentation for the @dataclass decorator:

TypeError will be raised if a field without a default value follows a field with a default value. This is true whether this occurs in a single class, or as a result of class inheritance.

However I wonder if it might be worth repeating in the section on Inheritance, perhaps with an example, and maybe the suggestion of avoiding the issue by using keyword-only arguments.

Linked PRs

• gh-153672

Comece pela seção vinculada sobre herança de dataclasses na documentação do Python e revise o PR gh-153672 antes de fazer alterações. Verifique os quatro exemplos desta issue em relação ao texto existente; considera-se concluído quando a documentação cobre explicitamente subclasses não decoradas, a coleta de campos segundo a MRO, argumentos do decorador em campos herdados e a ordenação entre campos com e sem valor padrão.