[Python-bugs-list] [ python-Bugs-671731 ] time module: time tuple not returned by certain functions

[SourceForge.net]

Bugs item #671731, was opened at 2003-01-21 03:14
You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=671731&group_id=5470

Category: Documentation
Group: Python 2.2.2
Status: Open
Resolution: None
>Priority: 3
Submitted By: Martin Miller (mrmiller)
Assigned to: Nobody/Anonymous (nobody)
Summary: time module: time tuple not returned by certain functions

Initial Comment:
On win32 the gmtime() and localtime() functions in the
time module return values of type 'time.time_struct'. I
believe the proper return value should be a tuple. This
is implied by the documentation (see
<http://www.python.org/doc/current/lib/module-time.html>
where it discusses the *time tuple* returned by the
various module functions and says it 'is a tuple of 9
integers'.

The time_struct value returned does behave like a tuple
instance in most respects, except that its type is not
type 'tuple'.

I think this is something that was changed in the not
too distant past, as I noticed the issue after
downloading code recently written by others which
depends on the type of the return value from these
functions being a tuple. If nothing else, if this was
changed, it is not backward compatible and the
documention ought to be updated.

Example:
> Python 2.2.2 (#37, Oct 14 2002, 17:02:34) [MSC 32 bit
(Intel)] on win32
> Type "help", "copyright", "credits" or "license" for
more information.
> >>> import time
> >>> print time.localtime()
> (2003, 1, 21, 3, 3, 2, 1, 21, 0)
> >>> print type(time.localtime()) is type(())
> 0
> >>> print type(time.localtime())
> <type 'time.struct_time'>
> >>>



----------------------------------------------------------------------

>Comment By: Martin Miller (mrmiller)
Date: 2003-01-24 12:55

Message:
Logged In: YES 
user_id=257085

The strcut_time return value change broke a module I had
downloaded called NormalDate by Jeff Bauer
<jbauer@rubic.com>. Fixing it myself turned out to be
relatively easy, once I determined what was the problem
(which was a little time-consuming, considering the fact
that the docs hadn't been updated). 

Later I located an updated version of module (v1.3) that had
been fixed by the author. The technique he used was to
create a private module attribute set to the type of value
returned from localtime(), so the updated module would still
work with versions of Python < 2.2.

The struct_time pseudo-sequence now returned by the
functions now sounds like a useful improvement, provided
that this fact is documented along with a description of
what the type is, which would allow others to also take
advantage of its attribute fetching behavior if they wished.
This could be done by copying the description in
<http://www.python.org/doc/current/whatsnew/node10.html>
into the developer documentation for the the time module
(and backporting that into the 2.2 documentation.

I'm lowering the priorty to 3 and marking it as a
documentation bug.




----------------------------------------------------------------------

Comment By: Michael Hudson (mwh)
Date: 2003-01-22 02:08

Message:
Logged In: YES 
user_id=6656

Oh yeah.  That should *definitely* be backported to the 2.2
docs. Could be more thorough, though.

----------------------------------------------------------------------

Comment By: Brett Cannon (bcannon)
Date: 2003-01-21 16:55

Message:
Logged In: YES 
user_id=357491

There is a mention of it in the developer docs at http://www.python.org/dev/doc/devel/lib/module-time.html .  The note for struct_time says what functions return a struct_time object.

A patch for the docs that changed everything else to say it returns a struct_time object instead of a time tuple wouldn't hurt, though.

----------------------------------------------------------------------

Comment By: Michael Hudson (mwh)
Date: 2003-01-21 03:40

Message:
Logged In: YES 
user_id=6656

This was very deliberate.  It *is* a bit shocking that the
docs didn't get updated, though.

There's a start of a description in:

http://www.python.org/doc/current/whatsnew/node10.html

Do you have code that actually broke because of this change?

----------------------------------------------------------------------

You can respond by visiting: 
https://sourceforge.net/tracker/?func=detail&atid=105470&aid=671731&group_id=5470