[Python-Dev] Docstrings on builtins
vano at mail.mipt.ru
Tue Jun 5 11:01:03 EDT 2018
On 05.06.2018 17:56, Chris Barker wrote:
> looking a bit deeper:
> In : timedelta.__new__.__doc__
> Out: 'Create and return a new object. See help(type) for accurate
> In : timedelta.__init__.__doc__
> Out: 'Initialize self. See help(type(self)) for accurate signature.'
> In : timedelta.__doc__
> Out: '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 : 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
Timedelta's one should probably do the same.
> On Mon, Jun 4, 2018 at 6:21 PM, Matthias Bussonnier
> <bussonniermatthias at gmail.com <mailto:bussonniermatthias at gmail.com>>
> 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
> 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.
> Python-Dev mailing list
> Python-Dev at python.org <mailto:Python-Dev at python.org>
> Christopher Barker, Ph.D.
> 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>
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the Python-Dev