Merged revisions 59407-59422 via svnmerge from

svn+ssh://pythondev@svn.python.org/python/trunk

........
  r59407 | armin.rigo | 2007-12-07 20:19:55 +0100 (Fri, 07 Dec 2007) | 2 lines

  This is probably what was meant here.
........
  r59410 | guido.van.rossum | 2007-12-08 05:38:23 +0100 (Sat, 08 Dec 2007) | 2 lines

  Be (just a bit :) more specific about release date.
........
  r59411 | alexandre.vassalotti | 2007-12-08 05:49:22 +0100 (Sat, 08 Dec 2007) | 3 lines

  Fix issue #1530.
  Return an error exit status if not all tests passes.
........
  r59413 | georg.brandl | 2007-12-08 11:56:39 +0100 (Sat, 08 Dec 2007) | 2 lines

  Fix tpyo.
........
  r59414 | georg.brandl | 2007-12-08 12:05:05 +0100 (Sat, 08 Dec 2007) | 2 lines

  Fix markup in whatsnew, use new directive in ACKS.
........
  r59415 | georg.brandl | 2007-12-08 12:05:36 +0100 (Sat, 08 Dec 2007) | 2 lines

  Fix Eren's name.
........
  r59416 | georg.brandl | 2007-12-08 12:23:13 +0100 (Sat, 08 Dec 2007) | 2 lines

  Add examples to the datetime documentation. Written for GHOP by "h4wk.cz".
........
  r59417 | skip.montanaro | 2007-12-08 15:37:43 +0100 (Sat, 08 Dec 2007) | 2 lines

  Note that open() is the preferred way to open files (issue 1510).
........
  r59418 | skip.montanaro | 2007-12-08 16:23:31 +0100 (Sat, 08 Dec 2007) | 1 line

  + "context manager"
........
  r59419 | skip.montanaro | 2007-12-08 16:26:16 +0100 (Sat, 08 Dec 2007) | 1 line

  correct email address
........
  r59420 | skip.montanaro | 2007-12-08 16:33:24 +0100 (Sat, 08 Dec 2007) | 3 lines

  When splitting, avoid making a copy of the string if the split doesn't find
  anything (issue 1538).
........

9 files changed, 307 insertions, 48 deletions

diff --git a/Doc/library/atexit.rst b/Doc/library/atexit.rst
index abef2fe..11b4120 100644
--- a/Doc/library/atexit.rst
+++ b/Doc/library/atexit.rst
@@ -4,8 +4,8 @@
 
 .. module:: atexit
    :synopsis: Register and execute cleanup functions.
-.. moduleauthor:: Skip Montanaro <skip@mojam.com>
-.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+.. moduleauthor:: Skip Montanaro <skip@pobox.com>
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
 
 The :mod:`atexit` module defines functions to register and unregister cleanup
diff --git a/Doc/library/bsddb.rst b/Doc/library/bsddb.rst
index aff1d5b..1b153c9 100644
--- a/Doc/library/bsddb.rst
+++ b/Doc/library/bsddb.rst
@@ -4,7 +4,7 @@
 
 .. module:: bsddb
    :synopsis: Interface to Berkeley DB database library
-.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
 
 The :mod:`bsddb` module provides an interface to the Berkeley DB library.  Users
diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 87a9bbd..adc1664 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -161,6 +161,7 @@ dates or times.
    Note that normalization of negative values may be surprising at first. For
    example, ::
 
+      >>> from datetime import timedelta
       >>> d = timedelta(microseconds=-1)
       >>> (d.days, d.seconds, d.microseconds)
       (-1, 86399, 999999)
@@ -264,6 +265,26 @@ comparison is ``==`` or ``!=``.  The latter cases return :const:`False` or
 efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
 considered to be true if and only if it isn't equal to ``timedelta(0)``.
 
+Example usage::
+    
+    >>> from datetime import timedelta
+    >>> year = timedelta(days=365)
+    >>> another_year = timedelta(weeks=40, days=84, hours=23, 
+    ...                          minutes=50, seconds=600)  # adds up to 365 days
+    >>> year == another_year
+    True
+    >>> ten_years = 10 * year
+    >>> ten_years, ten_years.days // 365
+    (datetime.timedelta(3650), 10)
+    >>> nine_years = ten_years - year
+    >>> nine_years, nine_years.days // 365
+    (datetime.timedelta(3285), 9)
+    >>> three_years = nine_years // 3;
+    >>> three_years, three_years.days // 365
+    (datetime.timedelta(1095), 3)
+    >>> abs(three_years - ten_years) == 2 * three_years + year
+    True
+
 
 .. _datetime-date:
 
@@ -485,6 +506,55 @@ Instance methods:
    Format codes referring to hours, minutes or seconds will see 0 values. See
    section :ref:`strftime-behavior`.
 
+Example of counting days to an event::
+
+    >>> import time
+    >>> from datetime import date
+    >>> today = date.today()
+    >>> today
+    datetime.date(2007, 12, 5)
+    >>> today == date.fromtimestamp(time.time())
+    True
+    >>> my_birthday = date(today.year, 6, 24)
+    >>> if my_birthday < today:
+    ...     my_birthday = my_birthday.replace(year=today.year + 1) 
+    >>> my_birthday
+    datetime.date(2008, 6, 24)
+    >>> time_to_birthday = abs(my_birthday - today) 
+    >>> time_to_birthday.days
+    202
+
+Example of working with :class:`date`::
+
+    >>> from datetime import date
+    >>> d = date.fromordinal(730920) # 730920th day after 1. 1. 0001
+    >>> d
+    datetime.date(2002, 3, 11)
+    >>> t = d.timetuple()
+    >>> for i in t:
+    ...     print i
+    2002                # year
+    3                   # month
+    11                  # day
+    0
+    0
+    0
+    0                   # weekday (0 = Monday)
+    70                  # 70th day in the year
+    -1
+    >>> ic = d.isocalendar()
+    >>> for i in ic:
+    ...     print i     # doctest: +SKIP
+    2002                # ISO year
+    11                  # ISO week number
+    1                   # ISO day number ( 1 = Monday )
+    >>> d.isoformat()
+    '2002-03-11'
+    >>> d.strftime("%d/%m/%y")
+    '11/03/02'
+    >>> d.strftime("%A %d. %B %Y")
+    'Monday 11. March 2002'
+
 
 .. _datetime-datetime:
 
@@ -919,6 +989,106 @@ Instance methods:
    Return a string representing the date and time, controlled by an explicit format
    string.  See section :ref:`strftime-behavior`.
 
+Examples of working with datetime objects::
+    
+    >>> from datetime import datetime, date, time
+    >>> # Using datetime.combine()
+    >>> d = date(2005, 7, 14)
+    >>> t = time(12, 30)
+    >>> datetime.combine(d, t)
+    datetime.datetime(2005, 7, 14, 12, 30)
+    >>> # Using datetime.now() or datetime.utcnow()
+    >>> datetime.now()
+    datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
+    >>> datetime.utcnow()
+    datetime.datetime(2007, 12, 6, 15, 29, 43, 79060)
+    >>> # Using datetime.strptime()
+    >>> dt = datetime.strptime("21/11/06 16:30", "%d/%m/%y %H:%M")
+    >>> dt
+    datetime.datetime(2006, 11, 21, 16, 30)
+    >>> # Using datetime.timetuple() to get tuple of all attributes
+    >>> tt = dt.timetuple()
+    >>> for it in tt:
+    ...     print it
+    ... 
+    2006    # year
+    11      # month
+    21      # day
+    16      # hour
+    30      # minute
+    0       # second
+    1       # weekday (0 = Monday)
+    325     # number of days since 1st January
+    -1      # dst - method tzinfo.dst() returned None
+    >>> # Date in ISO format
+    >>> ic = dt.isocalendar()
+    >>> for it in ic:
+    ...     print it
+    ...
+    2006    # ISO year
+    47      # ISO week
+    2       # ISO weekday
+    >>> # Formatting datetime
+    >>> dt.strftime("%A, %d. %B %Y %I:%M%p")
+    'Tuesday, 21. November 2006 04:30PM'
+
+Using datetime with tzinfo::
+
+    >>> from datetime import timedelta, datetime, tzinfo
+    >>> class GMT1(tzinfo):
+    ...     def __init__(self):         # DST starts last Sunday in March
+    ...         d = datetime(dt.year, 4, 1)   # ends last Sunday in October
+    ...         self.dston = d - timedelta(days=d.weekday() + 1)
+    ...         d = datetime(dt.year, 11, 1)    
+    ...         self.dstoff = d - timedelta(days=d.weekday() + 1)
+    ...     def utcoffset(self, dt):
+    ...         return timedelta(hours=1) + self.dst(dt)
+    ...     def dst(self, dt):              
+    ...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
+    ...             return timedelta(hours=1)
+    ...         else:
+    ...             return timedelta(0)
+    ...     def tzname(self,dt):
+    ...          return "GMT +1"
+    ... 
+    >>> class GMT2(tzinfo):
+    ...     def __init__(self):
+    ...         d = datetime(dt.year, 4, 1)  
+    ...         self.dston = d - timedelta(days=d.weekday() + 1)
+    ...         d = datetime(dt.year, 11, 1)    
+    ...         self.dstoff = d - timedelta(days=d.weekday() + 1)
+    ...     def utcoffset(self, dt):
+    ...         return timedelta(hours=1) + self.dst(dt)
+    ...     def dst(self, dt):
+    ...         if self.dston <=  dt.replace(tzinfo=None) < self.dstoff:
+    ...             return timedelta(hours=2)
+    ...         else:
+    ...             return timedelta(0)
+    ...     def tzname(self,dt):
+    ...         return "GMT +2"
+    ... 
+    >>> gmt1 = GMT1()
+    >>> # Daylight Saving Time
+    >>> dt1 = datetime(2006, 11, 21, 16, 30, tzinfo=gmt1)
+    >>> dt1.dst()
+    datetime.timedelta(0)
+    >>> dt1.utcoffset()
+    datetime.timedelta(0, 3600)
+    >>> dt2 = datetime(2006, 6, 14, 13, 0, tzinfo=gmt1)
+    >>> dt2.dst()
+    datetime.timedelta(0, 3600)
+    >>> dt2.utcoffset()
+    datetime.timedelta(0, 7200)
+    >>> # Convert datetime to another time zone
+    >>> dt3 = dt2.astimezone(GMT2())
+    >>> dt3     # doctest: +ELLIPSIS
+    datetime.datetime(2006, 6, 14, 14, 0, tzinfo=<GMT2 object at 0x...>)
+    >>> dt2     # doctest: +ELLIPSIS
+    datetime.datetime(2006, 6, 14, 13, 0, tzinfo=<GMT1 object at 0x...>)
+    >>> dt2.utctimetuple() == dt3.utctimetuple()
+    True
+ 
+
 
 .. _datetime-time:
 
@@ -1064,6 +1234,30 @@ Instance methods:
    ``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
    return ``None`` or a string object.
 
+Example::
+    
+    >>> from datetime import time, tzinfo
+    >>> class GMT1(tzinfo):
+    ...     def utcoffset(self, dt):
+    ...         return timedelta(hours=1) 
+    ...     def dst(self, dt):              
+    ...         return timedelta(0)
+    ...     def tzname(self,dt):
+    ...         return "Europe/Prague"
+    ...
+    >>> t = time(12, 10, 30, tzinfo=GMT1())
+    >>> t                               # doctest: +ELLIPSIS
+    datetime.time(12, 10, 30, tzinfo=<GMT1 object at 0x...>)
+    >>> gmt = GMT1()
+    >>> t.isoformat()
+    '12:10:30+01:00'
+    >>> t.dst()
+    datetime.timedelta(0)
+    >>> t.tzname()
+    'Europe/Prague'
+    >>> t.strftime("%H:%M:%S %Z")
+    '12:10:30 Europe/Prague'
+
 
 .. _datetime-tzinfo:
 
@@ -1277,7 +1471,7 @@ Applications that can't bear such ambiguities should avoid using hybrid
 :class:`tzinfo` subclasses; there are no ambiguities when using UTC, or any
 other fixed-offset :class:`tzinfo` subclass (such as a class representing only
 EST (fixed offset -5 hours), or only EDT (fixed offset -4 hours)).
-
+    
 
 .. _strftime-behavior:
 
@@ -1298,48 +1492,113 @@ For :class:`date` objects, the format codes for hours, minutes, and seconds
 should not be used, as :class:`date` objects have no such values.  If they're
 used anyway, ``0`` is substituted for them.
 
-For a naive object, the ``%z`` and ``%Z`` format codes are replaced by empty
-strings.
-
-For an aware object:
-
-``%z``
-   :meth:`utcoffset` is transformed into a 5-character string of the form +HHMM or
-   -HHMM, where HH is a 2-digit string giving the number of UTC offset hours, and
-   MM is a 2-digit string giving the number of UTC offset minutes.  For example, if
-   :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``, ``%z`` is
-   replaced with the string ``'-0330'``.
-
-``%Z``
-   If :meth:`tzname` returns ``None``, ``%Z`` is replaced by an empty string.
-   Otherwise ``%Z`` is replaced by the returned value, which must be a string.
-
 The full set of format codes supported varies across platforms, because Python
 calls the platform C library's :func:`strftime` function, and platform
-variations are common.  The documentation for Python's :mod:`time` module lists
-the format codes that the C standard (1989 version) requires, and those work on
-all platforms with a standard C implementation.  Note that the 1999 version of
-the C standard added additional format codes.
+variations are common.  
+
+The following is a list of all the format codes that the C standard (1989
+version) requires, and these work on all platforms with a standard C
+implementation.  Note that the 1999 version of the C standard added additional
+format codes.
 
 The exact range of years for which :meth:`strftime` works also varies across
 platforms.  Regardless of platform, years before 1900 cannot be used.
 
-.. % %% This example is obsolete, since strptime is now supported by datetime.
-.. % 
-.. % \subsection{Examples}
-.. % 
-.. % \subsubsection{Creating Datetime Objects from Formatted Strings}
-.. % 
-.. % The \class{datetime} class does not directly support parsing formatted time
-.. % strings.  You can use \function{time.strptime} to do the parsing and create
-.. % a \class{datetime} object from the tuple it returns:
-.. % 
-.. % \begin{verbatim}
-.. % >>> s = "2005-12-06T12:13:14"
-.. % >>> from datetime import datetime
-.. % >>> from time import strptime
-.. % >>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6])
-.. % datetime.datetime(2005, 12, 6, 12, 13, 14)
-.. % \end{verbatim}
-.. % 
++-----------+--------------------------------+-------+
+| Directive | Meaning                        | Notes |
++===========+================================+=======+
+| ``%a``    | Locale's abbreviated weekday   |       |
+|           | name.                          |       |
++-----------+--------------------------------+-------+
+| ``%A``    | Locale's full weekday name.    |       |
++-----------+--------------------------------+-------+
+| ``%b``    | Locale's abbreviated month     |       |
+|           | name.                          |       |
++-----------+--------------------------------+-------+
+| ``%B``    | Locale's full month name.      |       |
++-----------+--------------------------------+-------+
+| ``%c``    | Locale's appropriate date and  |       |
+|           | time representation.           |       |
++-----------+--------------------------------+-------+
+| ``%d``    | Day of the month as a decimal  |       |
+|           | number [01,31].                |       |
++-----------+--------------------------------+-------+
+| ``%H``    | Hour (24-hour clock) as a      |       |
+|           | decimal number [00,23].        |       |
++-----------+--------------------------------+-------+
+| ``%I``    | Hour (12-hour clock) as a      |       |
+|           | decimal number [01,12].        |       |
++-----------+--------------------------------+-------+
+| ``%j``    | Day of the year as a decimal   |       |
+|           | number [001,366].              |       |
++-----------+--------------------------------+-------+
+| ``%m``    | Month as a decimal number      |       |
+|           | [01,12].                       |       |
++-----------+--------------------------------+-------+
+| ``%M``    | Minute as a decimal number     |       |
+|           | [00,59].                       |       |
++-----------+--------------------------------+-------+
+| ``%p``    | Locale's equivalent of either  | \(1)  |
+|           | AM or PM.                      |       |
++-----------+--------------------------------+-------+
+| ``%S``    | Second as a decimal number     | \(2)  |
+|           | [00,61].                       |       |
++-----------+--------------------------------+-------+
+| ``%U``    | Week number of the year        | \(3)  |
+|           | (Sunday as the first day of    |       |
+|           | the week) as a decimal number  |       |
+|           | [00,53].  All days in a new    |       |
+|           | year preceding the first       |       |
+|           | Sunday are considered to be in |       |
+|           | week 0.                        |       |
++-----------+--------------------------------+-------+
+| ``%w``    | Weekday as a decimal number    |       |
+|           | [0(Sunday),6].                 |       |
++-----------+--------------------------------+-------+
+| ``%W``    | Week number of the year        | \(3)  |
+|           | (Monday as the first day of    |       |
+|           | the week) as a decimal number  |       |
+|           | [00,53].  All days in a new    |       |
+|           | year preceding the first       |       |
+|           | Monday are considered to be in |       |
+|           | week 0.                        |       |
++-----------+--------------------------------+-------+
+| ``%x``    | Locale's appropriate date      |       |
+|           | representation.                |       |
++-----------+--------------------------------+-------+
+| ``%X``    | Locale's appropriate time      |       |
+|           | representation.                |       |
++-----------+--------------------------------+-------+
+| ``%y``    | Year without century as a      |       |
+|           | decimal number [00,99].        |       |
++-----------+--------------------------------+-------+
+| ``%Y``    | Year with century as a decimal |       |
+|           | number.                        |       |
++-----------+--------------------------------+-------+
+| ``%z``    | UTC offset in the form +HHMM   | \(4)  |
+|           | or -HHMM (empty string if the  |       |
+|           | the object is naive).          |       |
++-----------+--------------------------------+-------+
+| ``%Z``    | Time zone name (empty string   |       |
+|           | if the object is naive).       |       |
++-----------+--------------------------------+-------+
+| ``%%``    | A literal ``'%'`` character.   |       |
++-----------+--------------------------------+-------+
 
+Notes:
+
+(1)
+   When used with the :func:`strptime` function, the ``%p`` directive only affects
+   the output hour field if the ``%I`` directive is used to parse the hour.
+
+(2)
+   The range really is ``0`` to ``61``; this accounts for leap seconds and the
+   (very rare) double leap seconds.
+
+(3)
+   When used with the :func:`strptime` function, ``%U`` and ``%W`` are only used in
+   calculations when the day of the week and the year are specified.
+
+(4)
+   For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
+   ``%z`` is replaced with the string ``'-0330'``.
diff --git a/Doc/library/mhlib.rst b/Doc/library/mhlib.rst
index 15d2b05..0dd5353 100644
--- a/Doc/library/mhlib.rst
+++ b/Doc/library/mhlib.rst
@@ -7,7 +7,7 @@
 
 
 .. % LaTeX'ized from the comments in the module by Skip Montanaro
-.. % <skip@mojam.com>.
+.. % <skip@pobox.com>.
 
 The :mod:`mhlib` module provides a Python interface to MH folders and their
 contents.
diff --git a/Doc/library/multifile.rst b/Doc/library/multifile.rst
index 3e79229..0614b86 100644
--- a/Doc/library/multifile.rst
+++ b/Doc/library/multifile.rst
@@ -155,7 +155,7 @@ Finally, :class:`MultiFile` instances have two public instance variables:
 :class:`MultiFile` Example
 --------------------------
 
-.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
 
 ::
diff --git a/Doc/library/readline.rst b/Doc/library/readline.rst
index 9426504..5399d3e 100644
--- a/Doc/library/readline.rst
+++ b/Doc/library/readline.rst
@@ -5,7 +5,7 @@
 .. module:: readline
    :platform: Unix
    :synopsis: GNU readline support for Python.
-.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
 
 The :mod:`readline` module defines a number of functions to facilitate
diff --git a/Doc/library/robotparser.rst b/Doc/library/robotparser.rst
index 1a66955..2451799 100644
--- a/Doc/library/robotparser.rst
+++ b/Doc/library/robotparser.rst
@@ -4,7 +4,7 @@
 
 .. module:: robotparser
    :synopsis: Loads a robots.txt file and answers questions about fetchability of other URLs.
-.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
 
 .. index::
diff --git a/Doc/library/telnetlib.rst b/Doc/library/telnetlib.rst
index 7f08e70..4c8ce45 100644
--- a/Doc/library/telnetlib.rst
+++ b/Doc/library/telnetlib.rst
@@ -4,7 +4,7 @@
 
 .. module:: telnetlib
    :synopsis: Telnet client class.
-.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
 
 .. index:: single: protocol; Telnet
diff --git a/Doc/library/urllib.rst b/Doc/library/urllib.rst
index f4c85bc..77eb632 100644
--- a/Doc/library/urllib.rst
+++ b/Doc/library/urllib.rst
@@ -363,7 +363,7 @@ Restrictions:
 URLopener Objects
 -----------------
 
-.. sectionauthor:: Skip Montanaro <skip@mojam.com>
+.. sectionauthor:: Skip Montanaro <skip@pobox.com>
 
 
 :class:`URLopener` and :class:`FancyURLopener` objects have the following