*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 abed...@gmail.com 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, 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
>> <https://www.python.org/dev/peps/pep-0526/>. 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.org
>> To unsubscribe send an email to python-id...@python.org
>> https://mail.python.org/mailman3/lists/python-ideas.python.org/
>> Message archived at
>> https://mail.python.org/archives/list/python...@python.org/message/4YJIVCZ5OIACU74UGZJECRMLTZWVDMOZ/
>>
>> <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...@python.org
>> To unsubscribe send an email to python-id...@python.org
>> https://mail.python.org/mailman3/lists/python-ideas.python.org/
>>
>> Message archived at
>> https://mail.python.org/archives/list/python...@python.org/message/5LUVCKIFIFV7FI6HT55L2PNCDE355LXC/
>>
>> <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/PWWJSICUARH5V5CAOIC4BFOPXWFC3HV6/
Code of Conduct: http://python.org/psf/codeofconduct/
