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 specify documentation.


On Tue, 2021-12-14 at 11:38 +1100, Steven D'Aprano wrote:
> 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 
> >         docstring. If you want to use Annotated but without a
> > docstring,
> >         put None in the second position.
> >         """
> >         spam: Annotated[int, 'Yummy meat-like product']
> >         eggs: Annotated[float, 'Goes well with spam', Domain[0, 1]]
> >         cheese: Sequence[str]  # No docstring.
> 
> perhaps a better convention might be that the docstring is the *last*
> item in the Annotated metadata, rather than the second item (after
> the 
> initial type).
> 
> The will allow people to use arbitrarily long augmented types, and 
> follow it with the docstring:
> 
>     spam: Annotated[int,
>                     Positive,
>                     GreaterThan[1],
>                     Union[Odd|Literal[2]],
>                     Prime,
>                     Wibble,
>                     Wobble,
>                     "Doc string goes here..."
>                     ]=2,
> 
> That will also help ensure that the docstring stands out visually, as
> it 
> will be last in the list, not stuck in the middle.
> 
> 

_______________________________________________
Python-ideas mailing list -- python-ideas@python.org
To unsubscribe send an email to python-ideas-le...@python.org
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at 
https://mail.python.org/archives/list/python-ideas@python.org/message/LKGQPLEOKJ5J5M4DWQIHLLVPXZE7ILSM/
Code of Conduct: http://python.org/psf/codeofconduct/

Reply via email to