Christopher Barker writes:
> but it is clear that the whole "are annotations only for typing"
> question will be made more clear.
Can we please stop posting this? AFAICS, the basic principle is
absolutely clear. For the foreseeable future:
1. Annotations are NOT "only for typing".
2. Uses
On Tue, Dec 14, 2021 at 06:48:57PM -0800, Paul Bryan wrote:
> Interesting. Some apparent downsides:
>
> - doesn't apply to class attributes
There is that.
> - objects with `__slots__` can't dynamically add attributes
Just give it a `__dict__` slot:
__slots__ = {'__dict__': None}
and now
On Tue, Dec 14, 2021, 9:49 PM Paul Bryan wrote:
> Interesting. Some apparent downsides:
>
> - doesn't apply to class attributes
> - objects with `__slots__` can't dynamically add attributes
>
Also doesn't apply to module level members.
To my mind these are significant downsides. And it also
Interesting. Some apparent downsides:
- doesn't apply to class attributes
- objects with `__slots__` can't dynamically add attributes
On Wed, 2021-12-15 at 11:13 +1100, Steven D'Aprano wrote:
> Hmmm, well it seems that we already have support for class attribute
> docstrings, since Python 3.8.
Hmmm, well it seems that we already have support for class attribute
docstrings, since Python 3.8.
It's not documented, but soon will be.
https://bugs.python.org/issue46076
class Card:
"""A card from a standard French deck"""
__slots__ = {
'suit': 'Either "Spades",
Hey all:
There is discussion RIGHT NOW in the SC, and on python-dev about future
"policy" around annotations, in response to the PEP 563 and 649 -- not
clear where it's going to end up, but it is clear that the whole "are
annotations only for typing" question will be made more clear.
Anyway, I
On Tue, Dec 14, 2021 at 10:23 AM Joao S. O. Bueno
wrote:
> Just a short one, for everyone agreeing type.Annotated does the job,
> but thinks we need new syntax, because it is verbose:
>
> You can already do:
>
> from typing import Annotated as A
>
> And:
>
> attr: A[type, "docstring goes
Just a short one, for everyone agreeing type.Annotated does the job,
but thinks we need new syntax, because it is verbose:
You can already do:
from typing import Annotated as A
And:
attr: A[type, "docstring goes here"]
I see no need for any new syntax.
(and maybe adding typing.Docstring
On Tue, Dec 14, 2021 at 12:38:55AM +0900, Stephen J. Turnbull wrote:
> Steven D'Aprano writes:
> > On Sun, Dec 12, 2021 at 08:44:25PM -0500, Ricky Teachey wrote:
>
> > > class C:
> > > x: Annotated [Any, "spam"]
> > >
> > > help(C.x)
> >
> > > And it seems reasonable to try and
On Mon, Dec 13, 2021 at 05:10:52PM -0800, Paul Bryan wrote:
> In other words, strings would be reserved to specify documentation.
We can't reserve strings to specify documentation.
(1) Strings can be used for forward references.
class Node:
payload: Any # Arbitrary data.
On 2021-12-13 17:07, Steven D'Aprano wrote:
>As an aside, seeing what the docs say about Annotated makes me think
>that "Annotated" is a very bad name for this thing. It confuses the
>idea of a type annotation (i.e., attached to a variable) with this
>type-incorporating-a-label, where
If we proceed with using `Annotated`, I suggest it be the last string
in the metadata. Using your example:
spam: Annotated[
int,
Positive,
GreaterThan[1],
"Doc string goes here..."
Union[Odd|Literal[2]],
Prime,
Wibble,
Wobble,
] = 2
In other words, strings would be reserved to
On Sun, Dec 12, 2021 at 07:43:16PM -0800, Brendan Barnwell wrote:
> The question is what does this annotate:
>
> Annotated[int, "some text here"]
Nothing. There's no annotation there.
That's an expression which returns a type alias. It is just an object.
You can print it, put it in a
Thinking more about my example here:
On Tue, Dec 14, 2021 at 01:50:45AM +1100, Steven D'Aprano wrote:
> class MyClass:
> """Blah blah blah.
>
> Variable annotations of the form Annotated[T, 'string', *args]
> always interpret the string in the second position as a
>
On Mon, Dec 13, 2021 at 6:54 AM Steven D'Aprano wrote:
>
> Okay, I'm sorry, I understand the statement to be referring to people
> who had no intention of using type-hints. For those people,
> no_type_hints is the right solution. But for those who want type hints
> as well as docstrings, it is
On Mon, Dec 13, 2021 at 7:14 AM Simão Afonso <
simao.afo...@powertools-tech.com> wrote:
> What about having a docstring but no typing information? In this case
> that's impossible, no?
spam: Annotated[Any, 'Yummy meat-like product']
or
spam: Annotated[None, 'Yummy meat-like product']
-CHB
Steven D'Aprano writes:
> On Sun, Dec 12, 2021 at 08:44:25PM -0500, Ricky Teachey wrote:
> > class C:
> > x: Annotated [Any, "spam"]
> >
> > help(C.x)
>
> > And it seems reasonable to try and create a way for it to work.
>
> By default, for arbitrary classes, no, it *shouldn't*
On 2021-12-14 01:50:45, Steven D'Aprano wrote:
> On Sun, Dec 12, 2021 at 12:23:54PM -0800, Christopher Barker wrote:
> > And I note that Annotated flattens nested Annotated types, so having both a
> > docstring and other use of Annotated could be a bit tricky.
>
> class MyClass:
>
On Sun, Dec 12, 2021 at 12:23:54PM -0800, Christopher Barker wrote:
> > the tools will follow. Runtime tools will
> > look at the dunder, static tools will look at the annotation directly.
> >
>
> I hope not. *maybe* inspect.get_annotations() though.
Sorry, I don't understand your position
On Sun, Dec 12, 2021 at 05:34:33PM -0800, Paul Bryan wrote:
> 1. While I agree that assigning the `Annotated` value to `SomeType`
> makes `SomeType` a type alias, what do you call the specific instance
> of `Annotated[...]` itself?
Its a type. The specific type is a private implementation
On Sun, Dec 12, 2021 at 08:44:25PM -0500, Ricky Teachey wrote:
> I'll go ahead and throw this out there: I was talking to a friend about
> this and he pointed out something simple but astute.
>
> Will this be expected to work?
>
> class C:
> x: Annotated [Any, "spam"]
>
> help(C.x)
>
>
On 2021-12-12 16:22, Steven D'Aprano wrote:
On Sun, Dec 12, 2021 at 03:38:23PM -0800, Paul Bryan wrote:
OK, so it's not the type, except it kind of is.
Except it isn't annotating the type, it is annotating the attribute.
We don't annotate *types*:
int: Sequence[str]
That would be a
I'll go ahead and throw this out there: I was talking to a friend about
this and he pointed out something simple but astute.
Will this be expected to work?
class C:
x: Annotated [Any, "spam"]
help(C.x)
Obviously it shouldn't as things stand now because that's an
AttributeError.
But if I'm
On Mon, 2021-12-13 at 11:22 +1100, Steven D'Aprano wrote:
> On Sun, Dec 12, 2021 at 03:38:23PM -0800, Paul Bryan wrote:
>
> > OK, so it's not the type, except it kind of is.
>
> Except it isn't annotating the type, it is annotating the attribute.
>
> We don't annotate *types*:
>
> int:
On Sun, Dec 12, 2021 at 03:46:16PM -0800, Christopher Barker wrote:
> I know what a wink means, but I have no idea what your actual point is.
My actual point is that the annotation:
attr: int
is annotating the attribute named "attr". That's pretty basic
stuff: if you don't think that
On Wed, Dec 08, 2021 at 11:50:55AM -, tmkehrenb...@gmail.com wrote:
> A few weeks ago, I proposed on this mailing list to write docstrings for
> class attributes like this:
>
> @dataclass
> class A:
> x: int
> """Docstring for x."""
Perhaps I missed it, but I haven't seen anyone
On Sun, Dec 12, 2021 at 03:38:23PM -0800, Paul Bryan wrote:
> OK, so it's not the type, except it kind of is.
Except it isn't annotating the type, it is annotating the attribute.
We don't annotate *types*:
int: Sequence[str]
That would be a regular variable or attribute called "int" that
On Sun, Dec 12, 2021 at 3:00 PM Steven D'Aprano wrote:
> > But what's being annotated, the type or the attribute?
>
> That's easy to test:
>
> >>> class A:
> ... attr: Annotated[int, "Doc string"]
> ...
> >>> int.__annotations__
> Traceback (most recent call last):
> File "", line 1, in
>
On Mon, 2021-12-13 at 09:57 +1100, Steven D'Aprano wrote:
> On Sun, Dec 12, 2021 at 12:48:36PM -0800, Paul Bryan wrote:
>
> > But what's being annotated, the type or the attribute?
>
> That's easy to test:
>
>
> > > > class A:
> ... attr: Annotated[int, "Doc string"]
> ...
> > > >
On Sun, Dec 12, 2021 at 12:48:36PM -0800, Paul Bryan wrote:
> But what's being annotated, the type or the attribute?
That's easy to test:
>>> class A:
... attr: Annotated[int, "Doc string"]
...
>>> int.__annotations__
Traceback (most recent call last):
File "", line 1, in
On Sun, 2021-12-12 at 12:23 -0800, Christopher Barker wrote:
> As for Typing.Annotated: it has one advantage in that typing tools
> currently (presumably) already accommodate extracting the type
> information from it -- see what typing.get_type_hints() does.
Confirmed. I have tooling today using
On Sat, Dec 11, 2021 at 10:55 PM Steven D'Aprano
wrote:
> If dataclasses, and other classes, move to using Annotated and
> __attrdoc__ for docstrings,
OK -- THAT is the point I brought up earlier, and you responded with "this
is settled" -- it's the __attrdoc__ part that needs to be
On Sun, Dec 12, 2021, 1:57 AM Steven D'Aprano wrote:
On Sun, Dec 12, 2021 at 12:38:06AM -0500, Ricky Teachey wrote:
> But Steve, since the most utilized documentation tool in the python
> universe, sphinx, doesn't look at Annotated
Yet.
> or in the lowercase-annotation part of an expression
Christopher Barker writes:
> However, what I haven’t seen in this thread is discussion of what I think
> is the key question:
>
> Where/how should class attribute doc strings be stored?
>
> Tacked on to the class __doc__ ?
-10. They need to be accessible via the attribute name. You
Okay, here we go:
```
import typing
def extract_docstrings(K):
"""Extract docstrings from the class K's annotations.
Class attribute docstrings are extracted from the second item
in Annotated[...] attributes. The original annotation is left
unchanged.
FIXME:
Handling
On Sun, Dec 12, 2021 at 12:38:06AM -0500, Ricky Teachey wrote:
> But Steve, since the most utilized documentation tool in the python
> universe, sphinx, doesn't look at Annotated
Yet.
> or in the lowercase-annotation part of an expression
Yet.
> for this and instead looks at a bare string
On Sat, Dec 11, 2021, 10:58 PM Steven D'Aprano wrote:
> On Sat, Dec 11, 2021 at 05:02:39PM -0800, Christopher Barker wrote:
> > On Sat, Dec 11, 2021 at 3:03 PM Steven D'Aprano
> wrote:
>
> > > Didn't we decide there was an existing feature for this, no need for
> > > new syntax?
>
> > Well, no.
On Sat, Dec 11, 2021 at 05:02:39PM -0800, Christopher Barker wrote:
> On Sat, Dec 11, 2021 at 3:03 PM Steven D'Aprano wrote:
> > Didn't we decide there was an existing feature for this, no need for
> > new syntax?
> Well, no. In fact, you could always put anything you wanted into an
>
On Sat, 2021-12-11 at 17:02 -0800, Christopher Barker wrote:
> It [Annotated] has a number of possible unspecified uses, but
> fundamentally, it's about the adding information to the type, not to
> the attribute -- e.g. not really intended for docstrings.
Ah, good point. I've conflated the two
On Sat, Dec 11, 2021 at 3:03 PM Steven D'Aprano wrote:
> On Sat, Dec 11, 2021 at 10:07:50AM -0800, Christopher Barker wrote:
> > Where/how should class attribute doc strings be stored?
> >
> > Tacked on to the class __doc__ ?
> > Another dict?
> > __attr_doc__
> > Added to __annotaions__ ?
> >
On Sat, Dec 11, 2021 at 10:49 AM Ricky Teachey wrote:
> The __annotations__ already exists. Is that a point in favor?
>
Yes and no. Right now, any object can be stored in annotations — having a
docstring tacked on would break who knows how much code.
However, there is the new
I think that because Sphinx could interpret strings below attributes
for documentation, that perhaps we should go in that direction in
Python proper.
Personally, I find this more readable:
class C:
x: Annotated[str, "Doc string"]
y: Annotated[int, "Doc string"]
over:
class C:
On Sat, Dec 11, 2021 at 10:07:50AM -0800, Christopher Barker wrote:
> Where/how should class attribute doc strings be stored?
>
> Tacked on to the class __doc__ ?
> Another dict?
> __attr_doc__
> Added to __annotaions__ ?
> Something else?
Didn't we decide there was an existing feature for
On Sat, Dec 11, 2021, 1:19 PM Christopher Barker
wrote:
>
>
> Where/how should class attribute doc strings be stored?
>
> Tacked on to the class __doc__ ?
>
> Another dict?
>
> __attr_doc__
>
> Added to __annotaions__ ?
>
> Something else?
>
> If they are to be available at run time, they
On Sat, Dec 11, 2021, 12:57 AM Stephen J. Turnbull <
stephenjturnb...@gmail.com> wrote:
Simão Afonso writes:
> On 2021-12-10 12:20:44, Ricky Teachey wrote:
> > I meant to ask about a (global) module member, not the module docstring
> > itself. Like MY_GLOBAL below:
> >
> > """This is the
On Fri, Dec 10, 2021 at 9:57 PM Stephen J. Turnbull <
stephenjturnb...@gmail.com> wrote:
> To my mind Sphinx is sufficiently widely used
And the system used for the official Python docs.
that this settles the
> "above or below" question.
So yes :-)
However, what I haven’t seen in this
Simão Afonso writes:
> On 2021-12-10 12:20:44, Ricky Teachey wrote:
> > I meant to ask about a (global) module member, not the module docstring
> > itself. Like MY_GLOBAL below:
> >
> > """This is the module docs"""
> >
> > MY_GLOBAL = None
> > """MY_GLOBAL docs"""
> >
> > Is this
On 2021-12-10 12:20:44, Ricky Teachey wrote:
> I meant to ask about a (global) module member, not the module docstring
> itself. Like MY_GLOBAL below:
>
> """This is the module docs"""
>
> MY_GLOBAL = None
> """MY_GLOBAL docs"""
>
> class CLS:
>"""CLS docs"""
>
>attr: int
>
On Fri, Dec 10, 2021 at 11:46 AM Simão Afonso <
simao.afo...@powertools-tech.com> wrote:
> On 2021-12-10 08:20:25, Ricky Teachey wrote:
> > Very very interesting that Sphinx already treats a bare string under the
> > parameter as documentation! I had no idea. Does it do the same thing at
> the
>
On 2021-12-10 08:20:25, Ricky Teachey wrote:
> Very very interesting that Sphinx already treats a bare string under the
> parameter as documentation! I had no idea. Does it do the same thing at the
> module level?
Yes.
> $ cat module.py
> """This is the module docs"""
>
> class CLS:
>
On Fri, Dec 10, 2021, 6:08 AM Simão Afonso
wrote:
> On 2021-12-09 12:47:28, Paul Bryan wrote:
> > On Thu, 2021-12-09 at 19:01 +, Simão Afonso wrote:
> > > I'm using docstrings bellow the attributes (analogous to functions
> > > and
> > > classes), I think it works well.
> > > It helps with
On 2021-12-09 12:47:28, Paul Bryan wrote:
> On Thu, 2021-12-09 at 19:01 +, Simão Afonso wrote:
> > I'm using docstrings bellow the attributes (analogous to functions
> > and
> > classes), I think it works well.
> > It helps with distinguishing the class docstring from the arguments.
>
> I
On Thu, Dec 9, 2021 at 3:23 PM Ricky Teachey wrote:
> On Thu, Dec 9, 2021 at 3:08 PM Christopher Barker
> wrote:
>
>> On Thu, Dec 9, 2021 at 11:08 AM Simão Afonso <
>> simao.afo...@powertools-tech.com> wrote:
>>
>>> Shouldn't typing be encouraged on dataclasses, at least?
>>
>>
>> Typing
On Thu, 2021-12-09 at 19:01 +, Simão Afonso wrote:
> I'm using docstrings bellow the attributes (analogous to functions
> and
> classes), I think it works well.
> It helps with distinguishing the class docstring from the arguments.
I think you'll find on close inspection that those strings
On Thu, Dec 9, 2021 at 3:08 PM Christopher Barker
wrote:
> On Thu, Dec 9, 2021 at 11:08 AM Simão Afonso <
> simao.afo...@powertools-tech.com> wrote:
>
>> Shouldn't typing be encouraged on dataclasses, at least?
>
>
> Typing shouldn’t be encouraged for any particular class, nor the language
>
On Thu, Dec 9, 2021 at 11:08 AM Simão Afonso <
simao.afo...@powertools-tech.com> wrote:
> Shouldn't typing be encouraged on dataclasses, at least?
Typing shouldn’t be encouraged for any particular class, nor the language
itself. Typing policy is a matter for the project/organization to decide.
I'm using docstrings bellow the attributes (analogous to functions and
classes), I think it works well.
It helps with distinguishing the class docstring from the arguments.
On 2021-12-08 13:25:55, Ricky Teachey wrote:
> On Wed, Dec 8, 2021 at 1:20 PM Paul Bryan wrote:
> > I believe a
On Thu, Dec 9, 2021 at 12:12 AM Paul Bryan wrote:
> On Thu, 2021-12-09 at 12:32 +1100, Steven D'Aprano wrote:
>
> On Wed, Dec 08, 2021 at 09:45:35AM -0800, Paul Bryan wrote:
>
> I propose there is already a viable option in typing.Annotated.
> Example:
>
> @dataclass
> class InventoryItem:
>
On Thu, 2021-12-09 at 12:32 +1100, Steven D'Aprano wrote:
> On Wed, Dec 08, 2021 at 09:45:35AM -0800, Paul Bryan wrote:
>
> > I propose there is already a viable option in typing.Annotated.
> > Example:
> >
> > @dataclass
> > class InventoryItem:
> > """Class for keeping track of an item in
On Wed, Dec 08, 2021 at 09:45:35AM -0800, Paul Bryan wrote:
> I propose there is already a viable option in typing.Annotated.
> Example:
>
> @dataclass
> class InventoryItem:
> """Class for keeping track of an item in inventory."""
>
> name: Annotated[str, "Short name of the
On 9/12/21 12:50 am, tmkehrenb...@gmail.com wrote:
The main criticism, I think, was that it is weird to have the docstring
*below* the attribute.
I don't think that's a problem. The docstring of a class or function
is also below the name of the class or function. I think it's
actually more
On Wed, Dec 8, 2021 at 1:20 PM Paul Bryan wrote:
> I believe a Annotated[..., str] could become an attribute docstring if by
> consensus we deem it to be so. I can't see any disadvantages, perhaps save
> for the verbosity of `Annotated`. It certainly seems like an advantage to
> use an existing
I believe a Annotated[..., str] could become an attribute docstring if
by consensus we deem it to be so. I can't see any disadvantages,
perhaps save for the verbosity of `Annotated`. It certainly seems like
an advantage to use an existing mechanism rather than define a new one
that would appear to
On Wed, Dec 8, 2021 at 12:46 PM Paul Bryan wrote:
> I propose there is already a viable option in typing.Annotated. Example:
>
> @dataclass
>
> class InventoryItem:
>
> """Class for keeping track of an item in inventory."""
>
> name: Annotated[str, "Short name of the item."]
>
>
On Wed, Dec 08, 2021 at 11:50:55AM -, tmkehrenb...@gmail.com wrote:
> A few weeks ago, I proposed on this mailing list to write docstrings for
> class attributes like this:
>
> @dataclass
> class A:
> x: int
> """Docstring for x."""
> ... is a normal string, except that it is stored
I propose there is already a viable option in typing.Annotated.
Example:
@dataclass
class InventoryItem:
"""Class for keeping track of an item in inventory."""
name: Annotated[str, "Short name of the item."]
unit_price: Annotated[float, "Price per unit in dollar."]
...
I've
On Wed, Dec 8, 2021 at 8:41 AM Steven D'Aprano wrote:
> On Wed, Dec 08, 2021 at 11:50:55AM -, tmkehrenb...@gmail.com wrote:
> > A few weeks ago, I proposed on this mailing list to write docstrings for
> > class attributes like this:
> >
> > @dataclass
> > class A:
> > x: int
> >
On Wed, Dec 08, 2021 at 11:50:55AM -, tmkehrenb...@gmail.com wrote:
> A few weeks ago, I proposed on this mailing list to write docstrings for
> class attributes like this:
>
> @dataclass
> class A:
> x: int
> """Docstring for x."""
>
> The main criticism, I think, was that it is
I think it's an interesting idea. I made the same or at least similar
suggestion in the previous thread, but it didn't receive any responses. I
assume this is because people weren't very interested (but I also
understand people are busy).
Here's that message:
69 matches
Mail list logo
