[Python-Dev] Docstrings on builtins

[Chris Barker]

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
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/python-dev/attachments/20180604/ebb8efaa/attachment.html>