On 12/21/2017 4:22 AM, Eric V. Smith wrote:
On 12/21/2017 1:46 AM, Chris Barker wrote:
I suggest that it be clear in the docs, and ideally in the PEP, that
the dataclass decorator is using the *annotation" syntax, and that the
the only relevant part it uses is that an annotation exists, but the
value of the annotation is essentially (completely?) ignored.
I think the PEP is very clear about this: "The dataclass decorator
examines the class to find fields. A field is defined as any variable
identified in __annotations__. That is, a variable that has a type
annotation. With two exceptions described below, none of the Data Class
machinery examines the type specified in the annotation."
This seems clear enough. It could come after describing what a
dataclass *is*.
I agree the docs should also be clear about this.
So we should have examples like:
@dataclass
class C:
a: ... # field with no default
b: ... = 0 # filed with a default value
Then maybe:
@dataclass
class C:
a: "the a parameter" # field with no default
b: "another, different parameter" = 0.0 # field with a default
Then the docs can go to say that if the user wants to specify a type
for use with a static type checking pre-processor, they can do it like
so:
@dataclass
class C:
a: int # integer field with no default
b: float = 0.0 # float field with a default
And the types will be recognized by type checkers such as mypy.
And I think the non-typed examples should go first in the docs.
Module some bike-shedding, the above seems pretty good to me.
I'll leave this for others to decide. The docs, and how approachable
they are to various audiences, isn't my area of expertise.
--
Terry Jan Reedy
_______________________________________________
Python-Dev mailing list
Python-Dev@python.org
https://mail.python.org/mailman/listinfo/python-dev
Unsubscribe:
https://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
