*I was hoping for something a little less verbose
I left out the word "verbose". I'll tripple check my next post. Sorry again.
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, 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...@python.orgTo unsubscribe send an email to python-id...@python.orgMessage archived at https://mail.python.org/archives/list/python...@python.org/message/4YJIVCZ5OIACU74UGZJECRMLTZWVDMOZ/Code of Conduct: http://python.org/psf/codeofconduct/_______________________________________________Python-ideas mailing list -- python...@python.orgTo unsubscribe send an email to python-id...@python.orgCode of Conduct: http://python.org/psf/codeofconduct/