Docstrings on builtins
Over on python-ideas, someone is/was proposing literals for timedeltas. I don't expect that will come to anything, but it did make me take a look at the docstring for datetime.timedelta. I use iPython's ? a lot for a quick overview of how to use a class/function. This is what I get: In [8]: timedelta? Init signature: timedelta(self, /, *args, **kwargs) Docstring: Difference between two datetime values. File: ~/miniconda2/envs/py3/lib/python3.6/datetime.py Type: type That is, well, not so useful. I'd like to see at least the signature: datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0 And ideally much of the text in the docs. I've noticed similarly minimal docstrings on a number of builtin functions and methods. If I wanted to contribute a PR to enhance these docstrings, where would they go? I've seen mention of "argument clinic", but really don't know quite what that is, or how it works, but it appears to be related. Anyway -- more comprehensive docstrings on buildins could really help Python's usability for command line usage. Thanks, - Chris -- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
Hi, For Argument Clinic, have a look at https://docs.python.org/dev/howto/clinic.html You can also try to copy/paste code from other files using Argument Clinic and then run "make clinic" to regenerate the generated files. Victor 2018-06-04 23:45 GMT+02:00 Chris Barker via Python-Dev <python-dev@python.org>:
Over on python-ideas, someone is/was proposing literals for timedeltas.
I don't expect that will come to anything, but it did make me take a look at the docstring for datetime.timedelta. I use iPython's ? a lot for a quick overview of how to use a class/function.
This is what I get:
In [8]: timedelta? Init signature: timedelta(self, /, *args, **kwargs) Docstring: Difference between two datetime values. File: ~/miniconda2/envs/py3/lib/python3.6/datetime.py Type: type
That is, well, not so useful. I'd like to see at least the signature:
datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0
And ideally much of the text in the docs.
I've noticed similarly minimal docstrings on a number of builtin functions and methods.
If I wanted to contribute a PR to enhance these docstrings, where would they go? I've seen mention of "argument clinic", but really don't know quite what that is, or how it works, but it appears to be related.
Anyway -- more comprehensive docstrings on buildins could really help Python's usability for command line usage.
Thanks, - Chris
--
Christopher Barker, Ph.D. Oceanographer
Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception
Chris.Barker@noaa.gov
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/vstinner%40redhat.com
On Mon, Jun 4, 2018 at 3:27 PM, Victor Stinner <vstinner@redhat.com> wrote:
For Argument Clinic, have a look at https://docs.python.org/dev/howto/clinic.html
Thanks Victor -- scanning that page, it is indeed where I needed to look. You can also try to copy/paste code from other files using Argument
Clinic and then run "make clinic" to regenerate the generated files.
good idea. Now to find some time to actually work on this... -CHB
Victor
Over on python-ideas, someone is/was proposing literals for timedeltas.
I don't expect that will come to anything, but it did make me take a look at the docstring for datetime.timedelta. I use iPython's ? a lot for a quick overview of how to use a class/function.
This is what I get:
In [8]: timedelta? Init signature: timedelta(self, /, *args, **kwargs) Docstring: Difference between two datetime values. File: ~/miniconda2/envs/py3/lib/python3.6/datetime.py Type: type
That is, well, not so useful. I'd like to see at least the signature:
datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0
And ideally much of the text in the docs.
I've noticed similarly minimal docstrings on a number of builtin functions and methods.
If I wanted to contribute a PR to enhance these docstrings, where would
2018-06-04 23:45 GMT+02:00 Chris Barker via Python-Dev < python-dev@python.org>: they
go? I've seen mention of "argument clinic", but really don't know quite what that is, or how it works, but it appears to be related.
Anyway -- more comprehensive docstrings on buildins could really help Python's usability for command line usage.
Thanks, - Chris
--
Christopher Barker, Ph.D. Oceanographer
Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception
Chris.Barker@noaa.gov
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/vstinner%40redhat.com
-- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
This may even be a bug/feature of IPython, I see that inspect.signature(timedelta) fails, so if timedelta? says Init signature: timedelta(self, /, *args, **kwargs) Then this may be some IPython internal logic. The timedelta class seem to use __new__ instead of __init__ (not sure why) and __new__ have a meaningful signature, So maybe we should fallback on that during signature inspection. Feel free to open an issue on the IPython repo. Btw IPython is uppercase I, and we don't want any troupe with the fruit giant. -- M On Mon, 4 Jun 2018 at 16:30, Chris Barker via Python-Dev < python-dev@python.org> wrote:
On Mon, Jun 4, 2018 at 3:27 PM, Victor Stinner <vstinner@redhat.com> wrote:
For Argument Clinic, have a look at https://docs.python.org/dev/howto/clinic.html
Thanks Victor -- scanning that page, it is indeed where I needed to look.
You can also try to copy/paste code from other files using Argument
Clinic and then run "make clinic" to regenerate the generated files.
good idea.
Now to find some time to actually work on this...
-CHB
Victor
Over on python-ideas, someone is/was proposing literals for timedeltas.
I don't expect that will come to anything, but it did make me take a look at the docstring for datetime.timedelta. I use iPython's ? a lot for a quick overview of how to use a class/function.
This is what I get:
In [8]: timedelta? Init signature: timedelta(self, /, *args, **kwargs) Docstring: Difference between two datetime values. File: ~/miniconda2/envs/py3/lib/python3.6/datetime.py Type: type
That is, well, not so useful. I'd like to see at least the signature:
datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0
And ideally much of the text in the docs.
I've noticed similarly minimal docstrings on a number of builtin functions and methods.
If I wanted to contribute a PR to enhance these docstrings, where would
2018-06-04 23:45 GMT+02:00 Chris Barker via Python-Dev < python-dev@python.org>: they
go? I've seen mention of "argument clinic", but really don't know quite what that is, or how it works, but it appears to be related.
Anyway -- more comprehensive docstrings on buildins could really help Python's usability for command line usage.
Thanks, - Chris
--
Christopher Barker, Ph.D. Oceanographer
Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception
Chris.Barker@noaa.gov
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe:
https://mail.python.org/mailman/options/python-dev/vstinner%40redhat.com
--
Christopher Barker, Ph.D. Oceanographer
Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception
Chris.Barker@noaa.gov _______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/bussonniermatthias%40gmai...
On 05.06.2018 3:09, Matthias Bussonnier wrote:
This may even be a bug/feature of IPython,
I see that inspect.signature(timedelta) fails, so if timedelta? says Init signature: timedelta(self, /, *args, **kwargs) Then this may be some IPython internal logic. The timedelta class seem to use __new__ instead of __init__ (not sure why)
Because it's an immutable type.
and __new__ have a meaningful signature, So maybe we should fallback on that during signature inspection.
According to https://stackoverflow.com/questions/4374006/check-for-mutability-in-python , there are no reliable tests for mutability.
Feel free to open an issue on the IPython repo.
Btw IPython is uppercase I, and we don't want any troupe with the fruit giant. -- M
On Mon, 4 Jun 2018 at 16:30, Chris Barker via Python-Dev <python-dev@python.org <mailto:python-dev@python.org>> wrote:
On Mon, Jun 4, 2018 at 3:27 PM, Victor Stinner <vstinner@redhat.com <mailto:vstinner@redhat.com>> wrote:
For Argument Clinic, have a look at https://docs.python.org/dev/howto/clinic.html
Thanks Victor -- scanning that page, it is indeed where I needed to look.
You can also try to copy/paste code from other files using Argument Clinic and then run "make clinic" to regenerate the generated files.
good idea.
Now to find some time to actually work on this...
-CHB
Victor
2018-06-04 23:45 GMT+02:00 Chris Barker via Python-Dev <python-dev@python.org <mailto:python-dev@python.org>>: > Over on python-ideas, someone is/was proposing literals for timedeltas. > > I don't expect that will come to anything, but it did make me take a look at > the docstring for datetime.timedelta. I use iPython's ? a lot for a quick > overview of how to use a class/function. > > This is what I get: > > In [8]: timedelta? > Init signature: timedelta(self, /, *args, **kwargs) > Docstring: Difference between two datetime values. > File: ~/miniconda2/envs/py3/lib/python3.6/datetime.py > Type: type > > > That is, well, not so useful. I'd like to see at least the signature: > > datetime.timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, > minutes=0, hours=0, weeks=0 > > And ideally much of the text in the docs. > > I've noticed similarly minimal docstrings on a number of builtin functions > and methods. > > If I wanted to contribute a PR to enhance these docstrings, where would they > go? I've seen mention of "argument clinic", but really don't know quite > what that is, or how it works, but it appears to be related. > > Anyway -- more comprehensive docstrings on buildins could really help > Python's usability for command line usage. > > Thanks, > - Chris > > > > > -- > > Christopher Barker, Ph.D. > Oceanographer > > Emergency Response Division > NOAA/NOS/OR&R (206) 526-6959 voice > 7600 Sand Point Way NE (206) 526-6329 fax > Seattle, WA 98115 (206) 526-6317 main reception > > Chris.Barker@noaa.gov <mailto:Chris.Barker@noaa.gov> > > _______________________________________________ > Python-Dev mailing list > Python-Dev@python.org <mailto:Python-Dev@python.org> > https://mail.python.org/mailman/listinfo/python-dev > Unsubscribe: > https://mail.python.org/mailman/options/python-dev/vstinner%40redhat.com >
--
Christopher Barker, Ph.D. Oceanographer
Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception
Chris.Barker@noaa.gov <mailto:Chris.Barker@noaa.gov> _______________________________________________ Python-Dev mailing list Python-Dev@python.org <mailto:Python-Dev@python.org> https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/bussonniermatthias%40gmai...
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/vano%40mail.mipt.ru
-- Regards, Ivan
On Mon, 4 Jun 2018 at 17:29, Ivan Pozdeev via Python-Dev < python-dev@python.org> wrote:
On 05.06.2018 3:09, Matthias Bussonnier wrote:
This may even be a bug/feature of IPython,
I see that inspect.signature(timedelta) fails, so if timedelta? says Init signature: timedelta(self, /, *args, **kwargs) Then this may be some IPython internal logic. The timedelta class seem to use __new__ instead of __init__ (not sure why)
Because it's an immutable type.
Ah, yes, thanks.
and __new__ have a meaningful signature, So maybe we should fallback on that during signature inspection.
According to https://stackoverflow.com/questions/4374006/check-for-mutability-in-python , there are no reliable tests for mutability.
Sure, but we can test if the signature of __init__ is (self,/, *args, **kwargs), and if it is, it is useless we can attempt to get the signature from __new__ and show that instead. We do similar things for docstrings, if __init__ have no docstring we look at the class level docstring. -- M
OK, looking a bit deeper: In [69]: timedelta.__new__.__doc__ Out[69]: 'Create and return a new object. See help(type) for accurate signature.' In [70]: timedelta.__init__.__doc__ Out[70]: 'Initialize self. See help(type(self)) for accurate signature.' In [71]: timedelta.__doc__ Out[71]: 'Difference between two datetime values.' So the none of the docstrings have the proper information. And: help(timedelta) returns: Help on class timedelta in module datetime: class timedelta(builtins.object) | Difference between two datetime values. | | Methods defined here: | | __abs__(self, /) | abs(self) | | __add__(self, value, /) | Return self+value. .... So no signature either. I'm guessing this is because argument clinic has not been properly applied -- so Ihave a PR to work on. but where does help() get its info anyway? I always thought docstrings were supposed to be used for the basic, well, docs. And between the class and __new__ and __init__, somewhere in there you should learn how to initialize an instance, yes? -CHB On Mon, Jun 4, 2018 at 6:21 PM, Matthias Bussonnier < bussonniermatthias@gmail.com> wrote:
On Mon, 4 Jun 2018 at 17:29, Ivan Pozdeev via Python-Dev < python-dev@python.org> wrote:
On 05.06.2018 3:09, Matthias Bussonnier wrote:
This may even be a bug/feature of IPython,
I see that inspect.signature(timedelta) fails, so if timedelta? says Init signature: timedelta(self, /, *args, **kwargs) Then this may be some IPython internal logic. The timedelta class seem to use __new__ instead of __init__ (not sure why)
Because it's an immutable type.
Ah, yes, thanks.
and __new__ have a meaningful signature, So maybe we should fallback on that during signature inspection.
According to https://stackoverflow.com/questions/4374006/check-for- mutability-in-python , there are no reliable tests for mutability.
Sure, but we can test if the signature of __init__ is (self,/, *args, **kwargs), and if it is, it is useless we can attempt to get the signature from __new__ and show that instead. We do similar things for docstrings, if __init__ have no docstring we look at the class level docstring. -- M
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/ chris.barker%40noaa.gov
-- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
On 05.06.2018 17:56, Chris Barker wrote:
OK,
looking a bit deeper:
In [69]: timedelta.__new__.__doc__ Out[69]: 'Create and return a new object. See help(type) for accurate signature.'
In [70]: timedelta.__init__.__doc__ Out[70]: 'Initialize self. See help(type(self)) for accurate signature.'
In [71]: timedelta.__doc__ Out[71]: 'Difference between two datetime values.'
So the none of the docstrings have the proper information. And:
help(timedelta) returns:
Help on class timedelta in module datetime:
class timedelta(builtins.object) | Difference between two datetime values. | | Methods defined here: | | __abs__(self, /) | abs(self) | | __add__(self, value, /) | Return self+value. ....
So no signature either.
I'm guessing this is because argument clinic has not been properly applied -- so Ihave a PR to work on.
but where does help() get its info anyway?
I always thought docstrings were supposed to be used for the basic, well, docs. And between the class and __new__ and __init__, somewhere in there you should learn how to initialize an instance, yes?
In [5]: print(str.__doc__) str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified <...> As you can see, the start of the type's docstring contains constructor signature(s). Timedelta's one should probably do the same.
-CHB
On Mon, Jun 4, 2018 at 6:21 PM, Matthias Bussonnier <bussonniermatthias@gmail.com <mailto:bussonniermatthias@gmail.com>> wrote:
On Mon, 4 Jun 2018 at 17:29, Ivan Pozdeev via Python-Dev <python-dev@python.org <mailto:python-dev@python.org>> wrote:
On 05.06.2018 3:09, Matthias Bussonnier wrote:
This may even be a bug/feature of IPython,
I see that inspect.signature(timedelta) fails, so if timedelta? says Init signature: timedelta(self, /, *args, **kwargs) Then this may be some IPython internal logic. The timedelta class seem to use __new__ instead of __init__ (not sure why)
Because it's an immutable type.
Ah, yes, thanks.
and __new__ have a meaningful signature, So maybe we should fallback on that during signature inspection.
According to https://stackoverflow.com/questions/4374006/check-for-mutability-in-python <https://stackoverflow.com/questions/4374006/check-for-mutability-in-python> , there are no reliable tests for mutability.
Sure, but we can test if the signature of __init__ is (self,/, *args, **kwargs), and if it is, it is useless we can attempt to get the signature from __new__ and show that instead. We do similar things for docstrings, if __init__ have no docstring we look at the class level docstring. -- M
_______________________________________________ Python-Dev mailing list Python-Dev@python.org <mailto:Python-Dev@python.org> https://mail.python.org/mailman/listinfo/python-dev <https://mail.python.org/mailman/listinfo/python-dev> Unsubscribe: https://mail.python.org/mailman/options/python-dev/chris.barker%40noaa.gov <https://mail.python.org/mailman/options/python-dev/chris.barker%40noaa.gov>
--
Christopher Barker, Ph.D. Oceanographer
Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception
Chris.Barker@noaa.gov <mailto:Chris.Barker@noaa.gov>
-- Regards, Ivan
On Tue, Jun 5, 2018 at 8:01 AM, Ivan Pozdeev <vano@mail.mipt.ru> wrote:
In [5]: print(str.__doc__) str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str
Create a new string object from the given object. If encoding or errors is specified <...>
As you can see, the start of the type's docstring contains constructor
signature(s).
And iPython does the "right thing" here, too:
In [7]: str? Init signature: str(self, /, *args, **kwargs) Docstring: str(object='') -> str str(bytes_or_buffer[, encoding[, errors]]) -> str Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to 'strict'. Type: type
Timedelta's one should probably do the same.
OK, I've found the docstring in the source and will submit a PR. -CHB
-CHB
On Mon, Jun 4, 2018 at 6:21 PM, Matthias Bussonnier < bussonniermatthias@gmail.com> wrote:
On Mon, 4 Jun 2018 at 17:29, Ivan Pozdeev via Python-Dev < python-dev@python.org> wrote:
On 05.06.2018 3:09, Matthias Bussonnier wrote:
This may even be a bug/feature of IPython,
I see that inspect.signature(timedelta) fails, so if timedelta? says Init signature: timedelta(self, /, *args, **kwargs) Then this may be some IPython internal logic. The timedelta class seem to use __new__ instead of __init__ (not sure why)
Because it's an immutable type.
Ah, yes, thanks.
and __new__ have a meaningful signature, So maybe we should fallback on that during signature inspection.
According to https://stackoverflow.com/ques tions/4374006/check-for-mutability-in-python , there are no reliable tests for mutability.
Sure, but we can test if the signature of __init__ is (self,/, *args, **kwargs), and if it is, it is useless we can attempt to get the signature from __new__ and show that instead. We do similar things for docstrings, if __init__ have no docstring we look at the class level docstring. -- M
_______________________________________________ Python-Dev mailing list Python-Dev@python.org https://mail.python.org/mailman/listinfo/python-dev Unsubscribe: https://mail.python.org/mailman/options/python-dev/chris. barker%40noaa.gov
--
Christopher Barker, Ph.D. Oceanographer
Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE <https://maps.google.com/?q=7600+Sand+Point+Way+NE&entry=gmail&source=g> (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception
Chris.Barker@noaa.gov
-- Regards, Ivan
-- Christopher Barker, Ph.D. Oceanographer Emergency Response Division NOAA/NOS/OR&R (206) 526-6959 voice 7600 Sand Point Way NE (206) 526-6329 fax Seattle, WA 98115 (206) 526-6317 main reception Chris.Barker@noaa.gov
participants (5)
-
Chris Barker -
Chris Barker - NOAA Federal
-
Ivan Pozdeev -
Matthias Bussonnier -
Victor Stinner