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 create a way for it to work.
> >
> > By default, for arbitrary classes, no, it *shouldn't* work, because for
> > arbitrary classes we cannot treat type hints as doc strings.
>
> Why not? In the sense that we establish a standard protocol for
> attaching them, and if there isn't one there, then 'help' would ignore
> that attribute or provide an empty docstring or whatever default
> action seems appropriate (presumably it would at least tell us the
> type! even if the hint is not an Annotated).
Anything is possible! And if this is for your own code you can do
anything you like.
But if you want this to be a language feature, that means getting
Steering Council approval, and while I don't speak for them, I am
confident, well, 90% confident, that they will agree with Guido that
*annotations are primarily for type-hinting*.
I am also confident (say, 75% confident) that they will *disagree* that
annotations are **only** for type-hinting, so there is that.
But of course if anyone thinks different, and believes that the SC will
bless "string annotations are docstrings" as a language feature, write a
PEP and go for it!
> > At least not without buy in from the core devs, including people like
> > Guido who care very much about typing. And that will probably need a
> > PEP.
>
> It's true that changing help will require buy-in from the core devs,
> as it's a built-in. But:
>
> > But to change the language
>
> Where's the language change? What am I missing? Or are you using
> this loosely to include builtins or even the whole stdlib?
Yes, it is somewhat loose, meaning the language proper, the builtins and
stdlib.
Right now, we have:
class C:
attr: expression
causes the annotation to be stored in the `__annotations__` dunder. If
all you want is to write your own metaclass or decorator to read the
__annotations__ and extract strings and stick them into C.mydocstrings,
you can do that right now, no questions asked.
But if you want to use a dunder like __attrdocs__, say, then dunders are
reserved for use for the language and we're supposed to ask first before
inventing new ones. So there's that.
And if you want this to new behaviour -- extracting strings from
annotations to use as docstrings -- to be in the language (including the
stdlib and builtins) then again we need approval. At the very least we
need at least one core dev to review, accept and merge the PR. And I
expect that the core devs would push it back to the typing group and
SC for a decision.
(That's what I would do if I knew how to merge PRs :-)
> It needs one thing: a standard place to put the documentation. I don't
> think just stuffing a string in __metadata__ is a good idea; that will
> be an annoyance to existing users of the __metadata__ attribute.
There is no guarantee or language-wide meaning to the metadata, every
consumer of Annotated type aliases *must* be prepared to skip metadata
they don't know how to process.
It's like consumers of email. The email headers can contain arbitrary
metadata that you have no clue how to handle, you are required to leave
it and skip over it.
But the beauty of Annotated is that it already exists and we can start
using it today. If anyone wishes to push for a syntax change, or a new
convenience type in the typing module:
attr: Docstring["this is a doc string"]
then you can do so, but you will still have to get the change approved.
And what are type checkers supposed to do with it? Now every type
checker has to learn to try Docstring as an alias for Any. What if you
want to declare a type as well?
> I think it probably should be an attribute on Annotated instances, to
> avoid tromping on existing uses of the __metadata__ attribute,
Is there a syntax change? If there is, then you definitely need SC
approval for syntax changed.
If not, how does the Annotated type know which piece of metadata gets
moved into the attribute?
Annotated[Any, fe, fi, fo, fum, "docstring", eeny, meany, miny, mo]
*We* can recognise that clearly item number 5 is the docstring, but how
does Annotated know? We need to have a set of rules in mind.
--
Steve
_______________________________________________
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/36IKKWZOC5ONCOSFI7OQPUD6PG64WP6L/
Code of Conduct: http://python.org/psf/codeofconduct/
