Add module helper function that provides access to all fields.

[ericvsmith]

Since we decided in issue #8 to use module level helper functions instead of instance methods, I want to add the first such function.

dataclasses.fields(cls) will return a tuple of Field objects defined in cls. Each Field object represents one field in the class.

This will be the basic building block for a number of introspection methods.

attrs returns object that can be either indexed or accessed by field name. I think that's a good idea, but I'm not going to implement it at first.

[gvanrossum]

I'm unclear on the API that attrs provides. Perhaps dataclasses can cover all bases by returning an OrderedDict mapping field names to Field objects in the order in which they occur in the class?

What should this do about inherited fields? Do they come first or last? (I guess first, to mimic how we'd imagine namedtuple or slots inheritance to work.)

[ericvsmith]

I'll respond later to your first point.

For the inherited fields, the order is the order that the fields are defined, starting from base classes working back toward the most-derived class (so, reverse MRO).

Here's an example from the tests, which show a base class that defines x and y, then a derived class that defines z and x. The order of fields is x, y, z, but x gets its Field definition from the most-derived class.

        @dataclass
        class Base:
            x: str = 'base'
            y: int = 0

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

        o = C1()
        self.assertEqual(repr(o), 'C1(x=15,y=0,z=10)')

[ericvsmith]

As far as the attrs API, this is taken from their documentation at http://www.attrs.org/en/stable/api.html#attr.fields. An attr.Attribute is the logical equivalent of what I'm calling a Field.

>>> @attr.s
... class C(object):
...     x = attr.ib()
...     y = attr.ib()
>>> attr.fields(C)
(Attribute(name='x', default=NOTHING, validator=None, repr=True, cmp=True, hash=None, init=True, convert=None, metadata=mappingproxy({})), Attribute(name='y', default=NOTHING, validator=None, repr=True, cmp=True, hash=None, init=True, convert=None, metadata=mappingproxy({})))
>>> attr.fields(C)[1]
Attribute(name='y', default=NOTHING, validator=None, repr=True, cmp=True, hash=None, init=True, convert=None, metadata=mappingproxy({}))
>>> attr.fields(C).y is attr.fields(C)[1]
True

So, the Attribute for y can be accessed as .y or [1].

I think using an OrderedDict is reasonable. I already build this data structure, but I just keep the values().

[ericvsmith]

A few points after reflecting on the attrs API:

1. attrs requires a class, not an instance, as the argument to attr.fields(cls). I'd prefer that dataclass.fields accepts either a class or instance. For comparison, namedtuple and typing.NamedTuple allow either for the similar ._fields attribute (because it's a class attribute there).

>>> T = namedtuple('T', 'x y')
>>> T._fields
('x', 'y')
>>> T(0, 1)._fields
('x', 'y')

2. attrs does type checking, and will raise an attrs-specific exception if it's not an attrs class:

>>> attr.fields(object)
Traceback (most recent call last):
...
attr.exceptions.NotAnAttrsClassError: <class 'object'> is not an attrs-decorated class.

I'd rather just live with the AttributeError, since the attribute name points you in the right direction:

>>> dataclass.fields(object)
Traceback (most recent call last):
...
AttributeError: type object 'object' has no attribute '__dataclass_fields__'

Especially so because I'm planning on adding a helper function to detect if a class/instance was created with @dataclass, so you can LBLY if you want.

[ericvsmith]

I've implemented this, but I'm going to leave the issue open for a day or so in case there are any comments about the API, specifically the points in #25 (comment).

[ilevkivskyi]

Few comments:

• I think reverse MRO makes perfect sense for the field order.
• We could allow both class and instance for fields, so that it will be easier to switch for people who are using named tuples.
• As for type checking I think we should just go with duck typing. Finally, someone might want to implement some kind of similar behavior (maybe even attrs will want some cross-compatibility) and now we have static support for duck typing (protocols).

By the way I am now working on implementing asdict and astuple, will make a PR today.

[gvanrossum]

Should we allow the example where a subclass overrides a field with a different type? IIUC mypy would complain unless you put a # type: ignore on it (then it will do the right thing).

[gvanrossum]

FWIW, I agree with the API as proposed in #25 (comment).

[ilevkivskyi]

@gvanrossum

Should we allow the example where a subclass overrides a field with a different type?

I think we should allow whatever is allowed by mypy.

[ericvsmith]

I think we should be liberal in what we allow. Who knows what reason someone might have for wanting this behavior? Maybe they just want to change from:

@dataclass
class Base:
   x: int
   # other useful fields or methods

to:

@dataclass
class C(Base):
   x: int = field(hash=False)

That is, the same as Base, but x would no longer be used in hashes of C instances.

I think if mypy complains, then that would make most people not use the feature, but I wouldn't want to limit someone who really wants it.

[gvanrossum]

Mypy has rules for these cases inspired by the Liskov Substitution Principle. A field's type in a subclass may be more restrictive than its type in a superclass.

So e.g. if it's a float in the superclass it could be an int in the subclass (since mypy considers int a subtype of float in this case). But switching from int to str is not allowed, because a function expecting a base class instance would access the attribute assuming it's an int, and be rudely surprised by the str from the subclass. (This is just an explanation of Liskov.)

However I think that changing some arguments to the field() call in the subclass should be fine, so the example would work.

[ilevkivskyi]

A field's type in a subclass may be more restrictive than its type in a superclass.

To clarify for @ericvsmith this also includes situations where the types are compatible because of Any. This is a nice escape hatch for things like covariant arguments etc.