A little less verbose:
import typing.Annotated as A
def request(
method: A[str, "The method to perform"],
url: A[str, "The URL to submit request to"],
...
) -> Response:
"""Constructs and sends a request."""
...
On Fri, 2021-01-29 at 13:43 -0800, [email protected] wrote:
> *I was hoping for something a little less verbose
>
> I left out the word "verbose". I'll tripple check my next post. Sorry
> again.
> On Friday, January 29, 2021 at 3:41:17 PM UTC-6 [email protected]
> wrote:
> > That could work. I'm not super familiar with typing.Annotated. I
> > was hoping for something a little less though my example doesn't
> > really show that with the way used commas.
> > Thinking about it more, it should be possible for the parser to
> > recognize a comma followed by a comment within a function
> > signature, so something like the following should be possible:
> >
> > def request(
> > method: str, # the method to perform
> > url: str, # the URL to submit request for
> > ...
> > ) -> Response: # the response to the request
> > """Constructs and sends a request."""
> > ...
> >
> > Though it's a bit of a special case because you can't remove the
> > white-space and get the same result:
> >
> > def request(method: str, # The method to perform url: str, # this
> > doesn't work ...
> > ) -> Response:
> > # This also is a bit weird
> > """Constructs and sends a request"""
> >
> > so maybe it's better to mandate that the doc be a string literal:
> >
> > def request(
> > method: str, "the method to perform"
> > url: str, "the URL to submit request for"
> > ...
> > ) -> Response: "the response to the request"
> > """Constructs and sends a request."""
> > ...
> >
> > Which would look weird with different white-space, but be
> > equivalent:
> >
> > def request(method: str, "The method to perform" url: str, "this
> > doesn't work" ...
> > ) -> Response:
> > """This also is a bit weird"""
> > """Constructs and sends a request"""
> >
> > The weirdest part about that is the doc string for "method" is
> > after the comma and precedes "url".
> >
> > Anyway, this was a half-baked thought for reducing some minor
> > repetition and putting documentation closer to where it's relevant.
> > If it comes at the expense of a lot of noise (Annotated[]
> > everywhere) or a confusing syntax hack (like above), it's probably
> > not worth it.
> > On Friday, January 29, 2021 at 2:46:55 PM UTC-6 Paul Bryan wrote:
> > > Or now, thinking more about it, why not simplify it by having a
> > > string literal in Annotated just represent its docstring?
> > >
> > > def request(
> > > method: Annotated[str, "The method to perform"],
> > > url: Annotated[str, "The URL to submit request to"],
> > > ...
> > > ) -> Response:
> > > """Constructs and sends a request."""
> > > ...
> > >
> > >
> > >
> > > On Fri, 2021-01-29 at 20:40 +0000, Paul Bryan wrote:
> > > > Perhaps this would be a good opportunity to start looking at
> > > > typing.Annotated[...] as a mechanism for parameter
> > > > documentation? Something like:
> > > >
> > > > def request(
> > > > method: Annotated[str, Doc("The method to perform")],
> > > > url: Annotated[str, Doc("The URL to submit request to")],
> > > > ...
> > > > ) -> Response:
> > > > """Constructs and sends a request."""
> > > > ...
> > > >
> > > >
> > > > On Fri, 2021-01-29 at 12:33 -0800, [email protected] wrote:
> > > > Sorry, I accidentally hit "post message" too soon. The idea is
> > > > that python would somehow construct a more complete doc-string
> > > > from the function doc-string and it's signature/parameter doc-
> > > > strings.
> > > >
> > > > On Friday, January 29, 2021 at 2:29:51 PM UTC-6
> > > > [email protected] wrote:
> > > > > Currently, python allows variable documentation via PEP 526.
> > > > > For most functions with short parameter lists that can fit in
> > > > > a reasonable column limit, I prefer the traditional
> > > > > declaration style with Google-style doc strings:
> > > > >
> > > > > def connect_to_next_port(self, minimum: int) => int:
> > > > > """Connects to the next available port.
> > > > >
> > > > > Args:
> > > > > minimum: A port value greater or equal to 1024.
> > > > >
> > > > > Returns:
> > > > > The new minimum port.
> > > > >
> > > > > Raises:
> > > > > ConnectionError: If no available port is found.
> > > > > """
> > > > > ...code...
> > > > >
> > > > > However, when a signature gets too long, I prefer to list the
> > > > > parameters vertically:
> > > > >
> > > > > def request(
> > > > > method: Method,
> > > > > url: Str,
> > > > > params: Dict = None,
> > > > > data: Dict = None,
> > > > > json: Str = None,
> > > > > headers: Dict = None,
> > > > > cookies: Dict = None,
> > > > > files: Dict = None,
> > > > > ...) => Response:
> > > > > """Constructs and sends a Request
> > > > >
> > > > > Args: ... """
> > > > >
> > > > > In which case, it would be nice to in-line some documentation
> > > > > instead of repeating the whole parameter list in the doc
> > > > > string. Something like:
> > > > >
> > > > > def request(
> > > > > method: Method
> > > > > #method for the new Request: ``GET``,``POST``, etc.
> > > > > ,
> > > > > url: Str
> > > > > #URL for the request
> > > > > ,
> > > > > params: Dict = None
> > > > > ...) => Response:
> > > > > """Constructs and sends a Request"""
> > > > >
> > > > >
> > > > >
> > > > >
> > > > _______________________________________________
> > > > Python-ideas mailing list -- [email protected]
> > > > To unsubscribe send an email to [email protected]
> > > > https://mail.python.org/mailman3/lists/python-ideas.python.org/
> > > > Message archived at
> > > >
> > >
> >
> https://mail.python.org/archives/list/[email protected]/message/4YJIVCZ5OIACU74UGZJECRMLTZWVDMOZ/
> > > > Code of Conduct: http://python.org/psf/codeofconduct/
> > > > _______________________________________________
> > > > Python-ideas mailing list -- [email protected]
> > > > To unsubscribe send an email to [email protected]
> > > > https://mail.python.org/mailman3/lists/python-ideas.python.org/
> > > > Message archived at
> > > >
> > >
> >
> https://mail.python.org/archives/list/[email protected]/message/5LUVCKIFIFV7FI6HT55L2PNCDE355LXC/
> > > > Code of Conduct: http://python.org/psf/codeofconduct/
> _______________________________________________
> Python-ideas mailing list -- [email protected]
> To unsubscribe send an email to [email protected]
> https://mail.python.org/mailman3/lists/python-ideas.python.org/
> Message archived at
> https://mail.python.org/archives/list/[email protected]/message/PWWJSICUARH5V5CAOIC4BFOPXWFC3HV6/
> Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________
Python-ideas mailing list -- [email protected]
To unsubscribe send an email to [email protected]
https://mail.python.org/mailman3/lists/python-ideas.python.org/
Message archived at
https://mail.python.org/archives/list/[email protected]/message/3G2MXTECHD4E5Y7QNFIZFNLWBW7FVMRC/
Code of Conduct: http://python.org/psf/codeofconduct/
