[Python-Dev] Docstrings on builtins

[Chris Barker]

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