[Python-Dev] Docstrings on builtins

Ivan Pozdeev vano at mail.mipt.ru
Mon Jun 4 20:28:32 EDT 2018


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.

> 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.

> 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 <mailto:python-dev at python.org>> wrote:
>
>     On Mon, Jun 4, 2018 at 3:27 PM, Victor Stinner
>     <vstinner at redhat.com <mailto: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 <mailto: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 <mailto:Chris.Barker at noaa.gov>
>         >
>         > _______________________________________________
>         > Python-Dev mailing list
>         > Python-Dev at python.org <mailto: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 <mailto:Chris.Barker at noaa.gov>
>     _______________________________________________
>     Python-Dev mailing list
>     Python-Dev at python.org <mailto: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
>
>
>
> _______________________________________________
> 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/vano%40mail.mipt.ru

-- 
Regards,
Ivan

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


More information about the Python-Dev mailing list