[Python-checkins] python/dist/src/Doc/lib libdatetime.tex,1.39,1.40

[tim_one@users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1:/tmp/cvs-serv21358/python/Doc/lib

Modified Files:
	libdatetime.tex 
Log Message:
date and datetime comparison:  when we don't know how to
compare against "the other" argument, we raise TypeError,
in order to prevent comparison from falling back to the
default (and worse than useless, in this case) comparison
by object address.

That's fine so far as it goes, but leaves no way for
another date/datetime object to make itself comparable
to our objects.  For example, it leaves Marc-Andre no way
to teach mxDateTime dates how to compare against Python
dates.

Discussion on Python-Dev raised a number of impractical
ideas, and the simple one implemented here:  when we don't
know how to compare against "the other" argument, we raise
TypeError *unless* the other object has a timetuple attr.
In that case, we return NotImplemented instead, and Python
will give the other object a shot at handling the
comparison then.

Note that comparisons of time and timedelta objects still
suffer the original problem, though.


Index: libdatetime.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/libdatetime.tex,v
retrieving revision 1.39
retrieving revision 1.40
diff -C2 -d -r1.39 -r1.40
*** libdatetime.tex	23 Jan 2003 20:53:07 -0000	1.39
--- libdatetime.tex	24 Jan 2003 22:36:30 -0000	1.40
***************
*** 382,385 ****
--- 382,393 ----
      date2 when date1 precedes date2 in time.  In other words,
      date1 < date2 if and only if date1.toordinal() < date2.toordinal().
+     \note{In order to stop comparison from falling back to the default
+           scheme of comparing object addresses, date comparison
+           normally raises \exception{TypeError} if the other comparand
+           isn't also a \class{date} object.  However, \code{NotImplemented}
+           is returned instead if the other comparand has a
+           \method{timetuple} attribute.  This hook gives other kinds of
+           date objects a chance at implementing mixed-type comparison.}
+ 
  
    \item
***************
*** 712,715 ****
--- 720,731 ----
      \member{tzinfo} members, the comparands are first adjusted by
      subtracting their UTC offsets (obtained from \code{self.utcoffset()}).
+     \note{In order to stop comparison from falling back to the default
+           scheme of comparing object addresses, datetime comparison
+           normally raises \exception{TypeError} if the other comparand
+           isn't also a \class{datetime} object.  However,
+           \code{NotImplemented} is returned instead if the other comparand
+           has a \method{timetuple} attribute.  This hook gives other
+           kinds of date objects a chance at implementing mixed-type
+           comparison.}
  
    \item