[Python-Dev] Docstrings on builtins

[Chris Barker]

On Tue, Jun 5, 2018 at 8:01 AM, Ivan Pozdeev <vano at 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 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/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 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
> <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 at 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 at noaa.gov
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20180606/57fb9624/attachment.html>