Improve documentation on `dataclass` inheritance

[MarkRotchell]

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.

[picnixz]

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.

What is however surprising to me is that is_dataclass(D) returns True. Granted, that's because it inherited the dataclass special fields, but I think dataclass inheritance wasn't meant to be used with multiple inheritance. A better design would to prefer composition over multiple inheritance of dataclasses here, but that's a matter of choice (sometimes multiple inheritance is easier).

For class E, it's the documented behavior. It says:

it looks through all of the class’s base classes in reverse MRO (that is, starting at object) and, for each dataclass that it finds, adds the fields from that base class to an ordered mapping of fields

So I don't think it's surprising here since we're decorating E.

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

I personally wasn't surprised that kw_only only applied to the new ones, because it would mean breaking the signatures expectations of base classes, but I wouldn't be against a small sentence saying that this doesn't apply to already inherited fields.

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.

I would choose only one place but we can say before introducing the docs of the decorator "See also Inheritance section". That way, we don't need to cover the subject twice.

cc @ericvsmith

[mpkocher]

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.

It might be worth mentioning that you can always drop back to make_dataclass. This won't have the limitations of inheritance and will rely on a simple and explicit mechanism of creating/munging a list of fields.

https://docs.python.org/3/library/dataclasses.html#dataclasses.make_dataclass

from dataclasses import dataclass, make_dataclass, field, KW_ONLY

tags = ('tags', list[str], field(default_factory=list))
core = [('name', str), ('age', int), tags]
modes = ('modes', set[str], field(default_factory=set))

A = make_dataclass('A', [core[0], core[1], ('modes', set[str], field(default_factory=set))])
B = make_dataclass('B', [core[0], ("_", KW_ONLY), tags])

a = A("Si", ["red", "blue"], modes={"alpha", "beta"})
b = B("Pb", tags=["yellow", "green"])
print(a, b)