[Python-Dev] Docstrings on builtins

[Matthias Bussonnier]

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 at python.org> wrote:

> On Mon, Jun 4, 2018 at 3:27 PM, Victor Stinner <vstinner at 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 at 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 at noaa.gov
>> >
>> > _______________________________________________
>> > 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/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 at noaa.gov
> _______________________________________________
> 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/bussonniermatthias%40gmail.com
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20180604/be600aa9/attachment-0001.html>