[Python-Dev] Docstrings on builtins

[Ivan Pozdeev]

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 at gmail.com <mailto:bussonniermatthias at gmail.com>> 
> wrote:
>
>
>
>     On Mon, 4 Jun 2018 at 17:29, Ivan Pozdeev via Python-Dev
>     <python-dev at python.org <mailto: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
>         <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 <mailto:Python-Dev at 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 at noaa.gov <mailto:Chris.Barker at noaa.gov>

-- 
Regards,
Ivan

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20180605/9c1035db/attachment.html>