[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 06: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: Closed
>Resolution: Fixed
Priority: 3
Submitted By: Martin Miller (mrmiller)
Assigned to: Fred L. Drake, Jr. (fdrake)
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: Fred L. Drake, Jr. (fdrake)
Date: 2003-02-04 10:19

Message:
Logged In: YES 
user_id=3066

The previous "fix" was pretty dodgy, I think, since I didn't
have a lot of time for it.  it really only added information
about the attributes, but did not change references to time
tuples throughout.  Perhaps it should have remained open,
pending a better fix.

I've checked in additional changes that provide more
thorough updates.

Doc/lib/libtime.tex 1.55, 1.48.6.4.

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

Comment By: Martin Miller (mrmiller)
Date: 2003-01-24 17:23

Message:
Logged In: YES 
user_id=257085

Looks like a duplicate of closed bug 604128
"time.struct_time undocumented" which was assigned and fixed
by fdrake on 2002-11-13. However I've looked at the
Doc/lib/libtime.tex file that included with 2.2.2 and see
nothing written about the type.

I'll try assigning this bug to him since I can't find the fix.


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

Comment By: Martin Miller (mrmiller)
Date: 2003-01-24 15: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 05: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 19: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 06: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