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
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4