This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: datetime module documentation missing critical detail
Type: Stage:
Components: Documentation Versions: Python 2.4
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: mwm, rhettinger, skip.montanaro, tim.peters
Priority: normal Keywords:

Created on 2004-12-17 19:22 by mwm, last changed 2022-04-11 14:56 by admin. This issue is now closed.

Messages (6)
msg23763 - (view) Author: Mike Meyer (mwm) Date: 2004-12-17 19:22
The datetime documentation - both pydoc and the manual - fail to
specify the arguments used to create a date/time/datetime object. The
manual implies that for date it's date(year, month, day), but that's
about it.

It would be nice if both could be extended to include examples. For date, say:

datetime.date(2004, 12, 25) - create a date object for christmas, 2004.

I can't give examples for time and datetime, because I'm not sure what
the format is.

msg23764 - (view) Author: Tim Peters (tim.peters) * (Python committer) Date: 2004-12-17 19:56
Logged In: YES 
user_id=31435

I'm not sure which docs you're looking at.  I'm looking at the 
Python docs <wink>, like here:

http://docs.python.org/lib/datetime-date.html

That seems very clear to me:

"""
class date(year, month, day) 

All arguments are required. Arguments may be ints or longs, in 
the following ranges: 

MINYEAR <= year <= MAXYEAR 
1 <= month <= 12 
1 <= day <= number of days in the given month and year 
If an argument outside those ranges is given, ValueError is 
raised. 
"""

There are equally precise docs for all the datetime.* classes.  
For example, you mentioned time:

"""
class time(hour[, minute[, second[, microsecond[, tzinfo]]]]) 

All arguments are optional. tzinfo may be None, or an 
instance of a tzinfo subclass. The remaining arguments may 
be ints or longs, in the following ranges: 

0 <= hour < 24 
0 <= minute < 60 
0 <= second < 60 
0 <= microsecond < 1000000. 

If an argument outside those ranges is given, ValueError is 
raised. All default to 0 except tzinfo, which defaults to None. 
"""
msg23765 - (view) Author: Mike Meyer (mwm) Date: 2004-12-17 20:23
Logged In: YES 
user_id=93910

You're right - I was just blind when reading the module documenation.

It would still be nice if I could get that information from
pydoc/help, though.


msg23766 - (view) Author: Skip Montanaro (skip.montanaro) * (Python triager) Date: 2004-12-17 21:05
Logged In: YES 
user_id=44345

Pydoc generates documentation based upon what it finds in
docstrings
and function signatures.  It can't get at the signatures of
functions
written in C.  In Python 2.4 pydoc generates a link to a
local or online
version of the docs for the subject module:

    NAME
	datetime - Fast implementation of the datetime type.

    FILE
	/Users/skip/local/lib/python2.5/lib-dynload/datetime.so

    MODULE DOCS
	http://www.python.org/doc/current/lib/module-datetime.html

    CLASSES
	__builtin__.object
	    date
		datetime
     ...

I think that's the best that can be done short of macroizing
the hell
out of C extension modules to allow function signatures to be
captured as attributes attached to the functions, similar to
what
GNU Emacs did many years ago.  Correct me if I'm wrong, but
I don't
think we want to go down that path (take a peek at the Emacs
source
if you are in doubt).
msg23767 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2004-12-17 22:28
Logged In: YES 
user_id=80475

It looks like the docstrings could be a bit more informative:

>>> print datetime.date.__doc__
Basic date type.

Compare that with:

>>> print collections.deque.__doc__
deque(iterable) --> deque object

Build an ordered collection accessible from endpoints only.
msg23768 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2004-12-19 20:17
Logged In: YES 
user_id=80475

Added slightly more informative docstrings for date, time,
and datetime.

See Modules/datetimemodule.c 1.76 and 1.75.2.1
History
Date User Action Args
2022-04-11 14:56:08adminsetgithub: 41336
2004-12-17 19:22:09mwmcreate