On 12/21/2017 1:46 AM, Chris Barker wrote:
On Wed, Dec 20, 2017 at 5:29 PM, Eric V. Smith <e...@trueblade.com
<mailto:e...@trueblade.com>> wrote:
There is definitely a passive bias towards using types with
dataclasses in that the Eric (the author) doesn't appear to want an
example without them in the pep/docs.
I'm not sure what such an example would look like. Do you mean
without annotations?
IIUC, there is not way to make a dataclass without annotations, yes?
That it, using annotations to determine the fields is the one and only
way the decorator works. So it's impossible to give an example without
annotations, yes?
Correct. Well, you will be able to use make_dataclass() without type
information after I fix bpo-32278, but most users won't be using that.
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."
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.
I'll leave this for others to decide. The docs, and how approachable
they are to various audiences, isn't my area of expertise.
This is completely analogous to how all the other parts of python are
taught. Would anyone suggest that the very first example of a function
definition that a newbie sees would be:
def func(a: int, b:float = 0.0):
body_of_function
Then, _maybe_ way down on the page, you mention that oh, by the way,
those types are completely ignored by Python. And not even give any
examples without types?
> Re-reading my post you referenced, is it just an example using
typing.Any?
I actually think that is exactly the wrong point -- typing.Any is still
using type hinting -- it's an explicit way to say, "any type will do",
but it's only relevant if you are using a type checker. We really need
examples for folks that don't know or care about type hinting at all.
typing.Any is for use by people that are explicitly adding type hinting,
and should be discussed in type hinting documentation.
> I'm okay with that in the docs, I just didn't want to focus on it in
the PEP. I want the PEP to only
> have the one reference to typing, for typing.ClassVar. I figure the
people reading the PEP can
> extrapolate to all of the possible uses for annotations that they
don't need to see a typing.Any
> example.
no they don't, but they DO need to see examples without type hints at all.
I'm not opposed to this in the documentation. Maybe we should decide on
a convention on what to use to convey "don't care". I've seen
typing.Any, None, ellipsis, strings, etc. all used.
Eric.
_______________________________________________
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
