[Python-checkins] python/nondist/sandbox/datetime doc.txt,1.41,1.42

[tim_one@users.sourceforge.net]

Update of /cvsroot/python/python/nondist/sandbox/datetime
In directory sc8-pr-cvs1:/tmp/cvs-serv31262

Modified Files:
	doc.txt 
Log Message:
Added docs for tzinfo.  I'm pretty sure these are full of holes.  For
example, can None be passed to tzinfo.tzname(), and if so, what should
tzinfo.tzname(None) do?  Note that if None cannot be passed to
tzinfo.tzname(), then how is timetz.tzname() supposed to work?  That is,
a timetz doesn't have a datetimetz available to pass back to tzinfo.


Index: doc.txt
===================================================================
RCS file: /cvsroot/python/python/nondist/sandbox/datetime/doc.txt,v
retrieving revision 1.41
retrieving revision 1.42
diff -C2 -d -r1.41 -r1.42
*** doc.txt	10 Dec 2002 21:21:13 -0000	1.41
--- doc.txt	10 Dec 2002 21:59:51 -0000	1.42
***************
*** 1,6 ****
  TODO/OPEN
  =========
! - Implement an abstract base tzinfo class semantics.  Variant tzinfo
!   classes must subclass from this.
  
  - datetimetz needs a C implementation.
--- 1,6 ----
  TODO/OPEN
  =========
! - Implement an abstract base tzinfo class.  Variant tzinfo classes must
!   subclass from this.
  
  - datetimetz needs a C implementation.
***************
*** 605,612 ****
  
  
- class datetimetz
- ================
- 
- 
  class time
  ==========
--- 605,608 ----
***************
*** 679,682 ****
--- 675,736 ----
      and second should not be used, since a time object has meaningful
      values only for those fields.
+ 
+ 
+ class tzinfo
+ ============
+ tzinfo is an abstract base clase, meaning that objects of this class
+ cannot be instantiated.  You need to derive a concrete subclass, and
+ supply implementations of (at least) the standard tzinfo methods.
+ The datetime module does not supply any concrete subclasses of tzinfo.
+ 
+ An instance of (a concrete subclass of) tzinfo can be passed to the
+ constructors for datetimetz and timetz objects.  The latter objects
+ view their fields as being in local time, and the tzinfo object supports
+ methods revealing offset of local time from UTC, and the name of the
+ time zone.
+ 
+ A concrete subclass of tzinfo must implement the following methods.
+ 
+   - __init__()
+     There are no special requirements on the constructor.
+     tzinfo.__init__() must not be called, since tzinfo is an abstract
+     class.
+ 
+ The remaining methods are normally called by a datetimetz object, in
+ response to the datetimetz method of the same name, passing itself as
+ the argument.  If dt.tzinfo is not None and not equal to self, an
+ exception should be raised:
+ 
+   - utcoffset(dt)
+     Return offset of local time from UTC, in minutes east of UTC.  If
+     local time is west of UTC, this should be negative.  Note that this
+     is intended to be the total offset from UTC; for example, if a
+     tzinfo object represents both time zone and DST adjustments,
+     utcoffset() should return their sum.  Return None if the UTC offset
+     isn't known.
+ 
+   - tzname(dt)
+     Return the timezone name corresponding to the date and time
+     represented by dt, as a string.  Nothing about string names is
+     defined by the datetime module, and there's no requirement that
+     it mean anything in particular.  For example, "GMT", "UTC", "-500",
+     "-5:00", "EDT", "US/Eastern", "America/New York" are all valid
+     replies.  Return None if a string name isn't known.  Note that
+     this is a method rather than a fixed string primarily because
+     some tzinfo objects will wish to return different names depending
+     on the specific value of dt passed, especially if the tzinfo class
+     is accounting for DST.
+ 
+   - dst(dt)
+     Return the DST offset, in minutes east of UTC, or None if DST
+     information isn't known.  Return 0 if DST is not in effect.
+     Note that DST offset, if applicable, has already been added to
+     the UTC offset returned by utcoffset(), so there's no need to
+     consult dst() unless you're interested in displaying DST info
+     separately.
+ 
+ 
+ class datetimetz
+ ================