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, abed...@gmail.com 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 abed...@gmail.com
> 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 -- 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/4YJIVCZ5OIACU74UGZJECRMLTZWVDMOZ/
> Code of Conduct: http://python.org/psf/codeofconduct/
> _______________________________________________
> 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/5LUVCKIFIFV7FI6HT55L2PNCDE355LXC/
> Code of Conduct: http://python.org/psf/codeofconduct/
_______________________________________________
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/IC4GKPTGGULZS5XSB5PT5G5ZPRL5SKWA/
Code of Conduct: http://python.org/psf/codeofconduct/
