[Python-Dev] Docstrings on builtins (original) (raw)

Chris Barker chris.barker at noaa.gov
Tue Jun 5 10:56:47 EDT 2018

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 at gmail.com> wrote:

On Mon, 4 Jun 2018 at 17:29, Ivan Pozdeev via Python-Dev <_ _python-dev at 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 at 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 at noaa.gov -------------- next part -------------- An HTML attachment was scrubbed... URL: <http://mail.python.org/pipermail/python-dev/attachments/20180605/74396b0c/attachment.html>

More information about the Python-Dev mailing list