--- rest25/library/datetime.rst	2008-12-19 16:58:07.000000000 +0900
+++ rest262/library/datetime.rst	2009-04-05 05:02:09.000000000 +0900
@@ -1,31 +1,30 @@
-.. % XXX what order should the types be discussed in?
-
-
 :mod:`datetime` --- Basic date and time types
 =============================================
 
 .. module:: datetime
    :synopsis: Basic date and time types.
 .. moduleauthor:: Tim Peters <tim@zope.com>
 .. sectionauthor:: Tim Peters <tim@zope.com>
 .. sectionauthor:: A.M. Kuchling <amk@amk.ca>
 
+.. XXX what order should the types be discussed in?
 
 .. versionadded:: 2.3
 
 The :mod:`datetime` module supplies classes for manipulating dates and times in
 both simple and complex ways.  While date and time arithmetic is supported, the
 focus of the implementation is on efficient member extraction for output
-formatting and manipulation.
+formatting and manipulation. For related
+functionality, see also the :mod:`time` and :mod:`calendar` modules.
 
 There are two kinds of date and time objects: "naive" and "aware". This
 distinction refers to whether the object has any notion of time zone, daylight
 saving time, or other kind of algorithmic or political time adjustment.  Whether
 a naive :class:`datetime` object represents Coordinated Universal Time (UTC),
 local time, or time in some other timezone is purely up to the program, just
 like it's up to the program whether a particular number represents metres,
 miles, or mass.  Naive :class:`datetime` objects are easy to understand and to
 work with, at the cost of ignoring some aspects of reality.
 
 For applications requiring more, :class:`datetime` and :class:`time` objects
 have an optional time zone information member, :attr:`tzinfo`, that can contain
@@ -130,52 +129,48 @@
 A :class:`timedelta` object represents a duration, the difference between two
 dates or times.
 
 
 .. class:: timedelta([days[, seconds[, microseconds[, milliseconds[, minutes[, hours[, weeks]]]]]]])
 
    All arguments are optional and default to ``0``.  Arguments may be ints, longs,
    or floats, and may be positive or negative.
 
    Only *days*, *seconds* and *microseconds* are stored internally.  Arguments are
    converted to those units:
 
-* A millisecond is converted to 1000 microseconds.
-
-* A minute is converted to 60 seconds.
-
-* An hour is converted to 3600 seconds.
-
-* A week is converted to 7 days.
+   * A millisecond is converted to 1000 microseconds.
+   * A minute is converted to 60 seconds.
+   * An hour is converted to 3600 seconds.
+   * A week is converted to 7 days.
 
    and days, seconds and microseconds are then normalized so that the
    representation is unique, with
 
-* ``0 <= microseconds < 1000000``
-
-* ``0 <= seconds < 3600*24`` (the number of seconds in one day)
-
-* ``-999999999 <= days <= 999999999``
+   * ``0 <= microseconds < 1000000``
+   * ``0 <= seconds < 3600*24`` (the number of seconds in one day)
+   * ``-999999999 <= days <= 999999999``
 
    If any argument is a float and there are fractional microseconds, the fractional
    microseconds left over from all arguments are combined and their sum is rounded
    to the nearest microsecond.  If no argument is a float, the conversion and
    normalization processes are exact (no information is lost).
 
    If the normalized value of days lies outside the indicated range,
    :exc:`OverflowError` is raised.
 
    Note that normalization of negative values may be surprising at first. For
-   example, ::
+   example,
 
+      >>> from datetime import timedelta
       >>> d = timedelta(microseconds=-1)
       >>> (d.days, d.seconds, d.microseconds)
       (-1, 86399, 999999)
 
 Class attributes are:
 
 
 .. attribute:: timedelta.min
 
    The most negative :class:`timedelta` object, ``timedelta(-999999999)``.
 
 
@@ -198,25 +193,25 @@
 +------------------+--------------------------------------------+
 | Attribute        | Value                                      |
 +==================+============================================+
 | ``days``         | Between -999999999 and 999999999 inclusive |
 +------------------+--------------------------------------------+
 | ``seconds``      | Between 0 and 86399 inclusive              |
 +------------------+--------------------------------------------+
 | ``microseconds`` | Between 0 and 999999 inclusive             |
 +------------------+--------------------------------------------+
 
 Supported operations:
 
-.. % XXX this table is too wide!
+.. XXX this table is too wide!
 
 +--------------------------------+-----------------------------------------------+
 | Operation                      | Result                                        |
 +================================+===============================================+
 | ``t1 = t2 + t3``               | Sum of *t2* and *t3*. Afterwards *t1*-*t2* == |
 |                                | *t3* and *t1*-*t3* == *t2* are true. (1)      |
 +--------------------------------+-----------------------------------------------+
 | ``t1 = t2 - t3``               | Difference of *t2* and *t3*. Afterwards *t1*  |
 |                                | == *t2* - *t3* and *t2* == *t1* + *t3* are    |
 |                                | true. (1)                                     |
 +--------------------------------+-----------------------------------------------+
 | ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer or long.       |
@@ -257,54 +252,72 @@
 In addition to the operations listed above :class:`timedelta` objects support
 certain additions and subtractions with :class:`date` and :class:`datetime`
 objects (see below).
 
 Comparisons of :class:`timedelta` objects are supported with the
 :class:`timedelta` object representing the smaller duration considered to be the
 smaller timedelta. In order to stop mixed-type comparisons from falling back to
 the default comparison by object address, when a :class:`timedelta` object is
 compared to an object of a different type, :exc:`TypeError` is raised unless the
 comparison is ``==`` or ``!=``.  The latter cases return :const:`False` or
 :const:`True`, respectively.
 
-:class:`timedelta` objects are hashable (usable as dictionary keys), support
+:class:`timedelta` objects are :term:`hashable` (usable as dictionary keys), support
 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:
 
 :class:`date` Objects
 ---------------------
 
 A :class:`date` object represents a date (year, month and day) in an idealized
 calendar, the current Gregorian calendar indefinitely extended in both
 directions.  January 1 of year 1 is called day number 1, January 2 of year 1 is
 called day number 2, and so on.  This matches the definition of the "proleptic
 Gregorian" calendar in Dershowitz and Reingold's book Calendrical Calculations,
 where it's the base calendar for all computations.  See the book for algorithms
 for converting between proleptic Gregorian ordinals and many other calendar
 systems.
 
 
 .. class:: date(year, month, day)
 
    All arguments are required.  Arguments may be ints or longs, in the following
    ranges:
 
-* ``MINYEAR <= year <= MAXYEAR``
-
-* ``1 <= month <= 12``
-
-* ``1 <= day <= number of days in the given month and year``
+   * ``MINYEAR <= year <= MAXYEAR``
+   * ``1 <= month <= 12``
+   * ``1 <= day <= number of days in the given month and year``
 
    If an argument outside those ranges is given, :exc:`ValueError` is raised.
 
 Other constructors, all class methods:
 
 
 .. method:: date.today()
 
    Return the current local date.  This is equivalent to
    ``date.fromtimestamp(time.time())``.
 
 
@@ -445,26 +458,25 @@
 .. method:: date.isoweekday()
 
    Return the day of the week as an integer, where Monday is 1 and Sunday is 7.
    For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also
    :meth:`weekday`, :meth:`isocalendar`.
 
 
 .. method:: date.isocalendar()
 
    Return a 3-tuple, (ISO year, ISO week number, ISO weekday).
 
    The ISO calendar is a widely used variant of the Gregorian calendar. See
-   `<http://www.phys.uu.nl/ vgent/calendar/isocalendar.htm>`_ for a good
-   explanation.
+   http://www.phys.uu.nl/ vgent/calendar/isocalendar.htm for a good explanation.
 
    The ISO year consists of 52 or 53 full weeks, and where a week starts on a
    Monday and ends on a Sunday.  The first week of an ISO year is the first
    (Gregorian) calendar week of a year containing a Thursday. This is called week
    number 1, and the ISO year of that Thursday is the same as its Gregorian year.
 
    For example, 2004 begins on a Thursday, so the first week of ISO year 2004
    begins on Monday, 29 Dec 2003 and ends on Sunday, 4 Jan 2004, so that
    ``date(2003, 12, 29).isocalendar() == (2004, 1, 1)`` and ``date(2004, 1,
    4).isocalendar() == (2004, 1, 7)``.
 
 
@@ -472,71 +484,116 @@
 
    Return a string representing the date in ISO 8601 format, 'YYYY-MM-DD'.  For
    example, ``date(2002, 12, 4).isoformat() == '2002-12-04'``.
 
 
 .. method:: date.__str__()
 
    For a date *d*, ``str(d)`` is equivalent to ``d.isoformat()``.
 
 
 .. method:: date.ctime()
 
-   Return a string representing the date, for example date(2002, 12, 4).ctime() ==
-   'Wed Dec  4 00:00:00 2002'. ``d.ctime()`` is equivalent to
+   Return a string representing the date, for example ``date(2002, 12,
+   4).ctime() == 'Wed Dec 4 00:00:00 2002'``. ``d.ctime()`` is equivalent to
    ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the native C
    :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which
    :meth:`date.ctime` does not invoke) conforms to the C standard.
 
 
 .. method:: date.strftime(format)
 
    Return a string representing the date, controlled by an explicit format string.
    Format codes referring to hours, minutes or seconds will see 0 values. See
-   section :ref:`strftime-behavior` -- :meth:`strftime` behavior.
+   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`:
+
+.. doctest::
+
+    >>> 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:     # doctest: +SKIP
+    ...     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:    # doctest: +SKIP
+    ...     print i
+    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:
 
 :class:`datetime` Objects
 -------------------------
 
 A :class:`datetime` object is a single object containing all the information
 from a :class:`date` object and a :class:`time` object.  Like a :class:`date`
 object, :class:`datetime` assumes the current Gregorian calendar extended in
 both directions; like a time object, :class:`datetime` assumes there are exactly
 3600\*24 seconds in every day.
 
 Constructor:
 
 
 .. class:: datetime(year, month, day[, hour[, minute[, second[, microsecond[, tzinfo]]]]])
 
    The year, month and day arguments are required.  *tzinfo* may be ``None``, or an
    instance of a :class:`tzinfo` subclass.  The remaining arguments may be ints or
    longs, in the following ranges:
 
-* ``MINYEAR <= year <= MAXYEAR``
-
-* ``1 <= month <= 12``
-
-* ``1 <= day <= number of days in the given month and year``
-
-* ``0 <= hour < 24``
-
-* ``0 <= minute < 60``
-
-* ``0 <= second < 60``
-
-* ``0 <= microsecond < 1000000``
+   * ``MINYEAR <= year <= MAXYEAR``
+   * ``1 <= month <= 12``
+   * ``1 <= day <= number of days in the given month and year``
+   * ``0 <= hour < 24``
+   * ``0 <= minute < 60``
+   * ``0 <= second < 60``
+   * ``0 <= microsecond < 1000000``
 
    If an argument outside those ranges is given, :exc:`ValueError` is raised.
 
 Other constructors, all class methods:
 
 
 .. method:: datetime.today()
 
    Return the current local datetime, with :attr:`tzinfo` ``None``. This is
    equivalent to ``datetime.fromtimestamp(time.time())``. See also :meth:`now`,
    :meth:`fromtimestamp`.
 
@@ -886,34 +943,35 @@
    The same as ``self.date().isoweekday()``. See also :meth:`weekday`,
    :meth:`isocalendar`.
 
 
 .. method:: datetime.isocalendar()
 
    Return a 3-tuple, (ISO year, ISO week number, ISO weekday).  The same as
    ``self.date().isocalendar()``.
 
 
 .. method:: datetime.isoformat([sep])
 
-   Return a string representing the date and time in ISO 8601 format, YYYY-MM-
-   DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0, YYYY-MM-DDTHH:MM:SS
-
-   If :meth:`utcoffset` does not return ``None``, a 6-character string is appended,
-   giving the UTC offset in (signed) hours and minutes: YYYY-MM-
-   DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0 YYYY-MM-
-   DDTHH:MM:SS+HH:MM
+   Return a string representing the date and time in ISO 8601 format,
+   YYYY-MM-DDTHH:MM:SS.mmmmmm or, if :attr:`microsecond` is 0,
+   YYYY-MM-DDTHH:MM:SS
+
+   If :meth:`utcoffset` does not return ``None``, a 6-character string is
+   appended, giving the UTC offset in (signed) hours and minutes:
+   YYYY-MM-DDTHH:MM:SS.mmmmmm+HH:MM or, if :attr:`microsecond` is 0
+   YYYY-MM-DDTHH:MM:SS+HH:MM
 
    The optional argument *sep* (default ``'T'``) is a one-character separator,
-   placed between the date and time portions of the result.  For example, ::
+   placed between the date and time portions of the result.  For example,
 
       >>> from datetime import tzinfo, timedelta, datetime
       >>> class TZ(tzinfo):
       ...     def utcoffset(self, dt): return timedelta(minutes=-399)
       ...
       >>> datetime(2002, 12, 25, tzinfo=TZ()).isoformat(' ')
       '2002-12-25 00:00:00-06:39'
 
 
 .. method:: datetime.__str__()
 
    For a :class:`datetime` instance *d*, ``str(d)`` is equivalent to
@@ -923,49 +981,148 @@
 .. method:: datetime.ctime()
 
    Return a string representing the date and time, for example ``datetime(2002, 12,
    4, 20, 30, 40).ctime() == 'Wed Dec  4 20:30:40 2002'``. ``d.ctime()`` is
    equivalent to ``time.ctime(time.mktime(d.timetuple()))`` on platforms where the
    native C :cfunc:`ctime` function (which :func:`time.ctime` invokes, but which
    :meth:`datetime.ctime` does not invoke) conforms to the C standard.
 
 
 .. method:: datetime.strftime(format)
 
    Return a string representing the date and time, controlled by an explicit format
-   string.  See section :ref:`strftime-behavior` -- :meth:`strftime` behavior.
+   string.  See section :ref:`strftime-behavior`.
+
+Examples of working with datetime objects:
+
+.. doctest::
+
+    >>> 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()   # doctest: +SKIP
+    datetime.datetime(2007, 12, 6, 16, 29, 43, 79043)   # GMT +1
+    >>> datetime.utcnow()   # doctest: +SKIP
+    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:   # doctest: +SKIP
+    ...     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:   # doctest: +SKIP
+    ...     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:
 
 :class:`time` Objects
 ---------------------
 
 A time object represents a (local) time of day, independent of any particular
 day, and subject to adjustment via a :class:`tzinfo` object.
 
 
 .. class:: time(hour[, minute[, second[, microsecond[, tzinfo]]]])
 
    All arguments are optional.  *tzinfo* may be ``None``, or an instance of a
    :class:`tzinfo` subclass.  The remaining arguments may be ints or longs, in the
    following ranges:
 
-* ``0 <= hour < 24``
-
-* ``0 <= minute < 60``
-
-* ``0 <= second < 60``
-
-* ``0 <= microsecond < 1000000``.
+   * ``0 <= hour < 24``
+   * ``0 <= minute < 60``
+   * ``0 <= second < 60``
+   * ``0 <= microsecond < 1000000``.
 
    If an argument outside those ranges is given, :exc:`ValueError` is raised.  All
    default to ``0`` except *tzinfo*, which defaults to :const:`None`.
 
 Class attributes:
 
 
 .. attribute:: time.min
 
    The earliest representable :class:`time`, ``time(0, 0, 0, 0)``.
 
 
@@ -1048,100 +1205,124 @@
    6-character string is appended, giving the UTC offset in (signed) hours and
    minutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM
 
 
 .. method:: time.__str__()
 
    For a time *t*, ``str(t)`` is equivalent to ``t.isoformat()``.
 
 
 .. method:: time.strftime(format)
 
    Return a string representing the time, controlled by an explicit format string.
-   See section :ref:`strftime-behavior` -- :meth:`strftime` behavior.
+   See section :ref:`strftime-behavior`.
 
 
 .. method:: time.utcoffset()
 
    If :attr:`tzinfo` is ``None``, returns ``None``, else returns
    ``self.tzinfo.utcoffset(None)``, and raises an exception if the latter doesn't
    return ``None`` or a :class:`timedelta` object representing a whole number of
    minutes with magnitude less than one day.
 
 
 .. method:: time.dst()
 
    If :attr:`tzinfo` is ``None``, returns ``None``, else returns
    ``self.tzinfo.dst(None)``, and raises an exception if the latter doesn't return
    ``None``, or a :class:`timedelta` object representing a whole number of minutes
    with magnitude less than one day.
 
 
 .. method:: time.tzname()
 
    If :attr:`tzinfo` is ``None``, returns ``None``, else returns
    ``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:
 
 :class:`tzinfo` Objects
 -----------------------
 
-:class:`tzinfo` is an abstract base clase, meaning that this class should not be
+:class:`tzinfo` is an abstract base class, meaning that this class should not be
 instantiated directly.  You need to derive a concrete subclass, and (at least)
 supply implementations of the standard :class:`tzinfo` methods needed by the
 :class:`datetime` methods you use.  The :mod:`datetime` module does not supply
 any concrete subclasses of :class:`tzinfo`.
 
 An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
 constructors for :class:`datetime` and :class:`time` objects. The latter objects
 view their members as being in local time, and the :class:`tzinfo` object
 supports methods revealing offset of local time from UTC, the name of the time
 zone, and DST offset, all relative to a date or time object passed to them.
 
 Special requirement for pickling:  A :class:`tzinfo` subclass must have an
 :meth:`__init__` method that can be called with no arguments, else it can be
 pickled but possibly not unpickled again.  This is a technical requirement that
 may be relaxed in the future.
 
 A concrete subclass of :class:`tzinfo` may need to implement the following
 methods.  Exactly which methods are needed depends on the uses made of aware
 :mod:`datetime` objects.  If in doubt, simply implement all of them.
 
 
-.. method:: XXX Class.utcoffset(self, dt)
+.. method:: tzinfo.utcoffset(self, 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 :class:`tzinfo` object represents both
    time zone and DST adjustments, :meth:`utcoffset` should return their sum.  If
    the UTC offset isn't known, return ``None``.  Else the value returned must be a
    :class:`timedelta` object specifying a whole number of minutes in the range
    -1439 to 1439 inclusive (1440 = 24\*60; the magnitude of the offset must be less
    than one day).  Most implementations of :meth:`utcoffset` will probably look
    like one of these two::
 
       return CONSTANT                 # fixed-offset class
       return CONSTANT + self.dst(dt)  # daylight-aware class
 
    If :meth:`utcoffset` does not return ``None``, :meth:`dst` should not return
    ``None`` either.
 
    The default implementation of :meth:`utcoffset` raises
    :exc:`NotImplementedError`.
 
 
-.. method:: XXX Class.dst(self, dt)
+.. method:: tzinfo.dst(self, dt)
 
    Return the daylight saving time (DST) adjustment, in minutes east of UTC, or
    ``None`` if DST information isn't known.  Return ``timedelta(0)`` if DST is not
    in effect. If DST is in effect, return the offset as a :class:`timedelta` object
    (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
    already been added to the UTC offset returned by :meth:`utcoffset`, so there's
    no need to consult :meth:`dst` unless you're interested in obtaining DST info
    separately.  For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo`
    member's :meth:`dst` method to determine how the :attr:`tm_isdst` flag should be
    set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for DST changes
    when crossing time zones.
 
@@ -1171,25 +1352,25 @@
           # Code to set dston and dstoff to the time zone's DST
           # transition times based on the input dt.year, and expressed
           # in standard local time.  Then
 
           if dston <= dt.replace(tzinfo=None) < dstoff:
               return timedelta(hours=1)
           else:
               return timedelta(0)
 
    The default implementation of :meth:`dst` raises :exc:`NotImplementedError`.
 
 
-.. method:: XXX Class.tzname(self, dt)
+.. method:: tzinfo.tzname(self, dt)
 
    Return the time zone name corresponding to the :class:`datetime` object *dt*, as
    a string. Nothing about string names is defined by the :mod:`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 :class:`tzinfo`
    subclasses will wish to return different names depending on the specific value
    of *dt* passed, especially if the :class:`tzinfo` class is accounting for
    daylight time.
 
    The default implementation of :meth:`tzname` raises :exc:`NotImplementedError`.
@@ -1206,25 +1387,25 @@
 may be more useful for ``utcoffset(None)`` to return the standard UTC offset, as
 there is no other convention for discovering the standard offset.
 
 When a :class:`datetime` object is passed in response to a :class:`datetime`
 method, ``dt.tzinfo`` is the same object as *self*.  :class:`tzinfo` methods can
 rely on this, unless user code calls :class:`tzinfo` methods directly.  The
 intent is that the :class:`tzinfo` methods interpret *dt* as being in local
 time, and not need worry about objects in other timezones.
 
 There is one more :class:`tzinfo` method that a subclass may wish to override:
 
 
-.. method:: XXX Class.fromutc(self, dt)
+.. method:: tzinfo.fromutc(self, dt)
 
    This is called from the default :class:`datetime.astimezone()` implementation.
    When called from that, ``dt.tzinfo`` is *self*, and *dt*'s date and time members
    are to be viewed as expressing a UTC time.  The purpose of :meth:`fromutc` is to
    adjust the date and time members, returning an equivalent datetime in *self*'s
    local time.
 
    Most :class:`tzinfo` subclasses should be able to inherit the default
    :meth:`fromutc` implementation without problems.  It's strong enough to handle
    fixed-offset time zones, and time zones accounting for both standard and
    daylight time, and the latter even if the DST transition times differ in
    different years.  An example of a time zone the default :meth:`fromutc`
@@ -1245,27 +1426,26 @@
           delta = dtoff - dtdst  # this is self's standard offset
           if delta:
               dt += delta   # convert to standard local time
               dtdst = dt.dst()
               # raise ValueError if dtdst is None
           if dtdst:
               return dt + dtdst
           else:
               return dt
 
 Example :class:`tzinfo` classes:
 
+.. literalinclude:: ../includes/tzinfo-examples.py
 
-.. include:: ../includes/tzinfo-examples.py
-   :literal:
 
 Note that there are unavoidable subtleties twice per year in a :class:`tzinfo`
 subclass accounting for both standard and daylight time, at the DST transition
 points.  For concreteness, consider US Eastern (UTC -0500), where EDT begins the
 minute after 1:59 (EST) on the first Sunday in April, and ends the minute after
 1:59 (EDT) on the last Sunday in October::
 
      UTC   3:MM  4:MM  5:MM  6:MM  7:MM  8:MM
      EST  22:MM 23:MM  0:MM  1:MM  2:MM  3:MM
      EDT  23:MM  0:MM  1:MM  2:MM  3:MM  4:MM
 
    start  22:MM 23:MM  0:MM  1:MM  3:MM  4:MM
@@ -1304,60 +1484,162 @@
 -------------------------
 
 :class:`date`, :class:`datetime`, and :class:`time` objects all support a
 ``strftime(format)`` method, to create a string representing the time under the
 control of an explicit format string.  Broadly speaking, ``d.strftime(fmt)``
 acts like the :mod:`time` module's ``time.strftime(fmt, d.timetuple())``
 although not all objects support a :meth:`timetuple` method.
 
 For :class:`time` objects, the format codes for year, month, and day should not
 be used, as time objects have no such values.  If they're used anyway, ``1900``
 is substituted for the year, and ``0`` for the month and day.
 
-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 :class:`date` objects, the format codes for hours, minutes, seconds, and
+microseconds should not be used, as :class:`date` objects have no such
+values.  If they're used anyway, ``0`` is substituted for them.
+
+.. versionadded:: 2.6
+   :class:`time` and :class:`datetime` objects support a ``%f`` format code
+   which expands to the number of microseconds in the object, zero-padded on
+   the left to six places.
 
 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.
 
++-----------+--------------------------------+-------+
+| 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].                |       |
++-----------+--------------------------------+-------+
+| ``%f``    | Microsecond as a decimal       | \(1)  |
+|           | number [0,999999], zero-padded |       |
+|           | on the left                    |       |
++-----------+--------------------------------+-------+
+| ``%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  | \(2)  |
+|           | AM or PM.                      |       |
++-----------+--------------------------------+-------+
+| ``%S``    | Second as a decimal number     | \(3)  |
+|           | [00,61].                       |       |
++-----------+--------------------------------+-------+
+| ``%U``    | Week number of the year        | \(4)  |
+|           | (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        | \(4)  |
+|           | (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   | \(5)  |
+|           | or -HHMM (empty string if the  |       |
+|           | the object is naive).          |       |
++-----------+--------------------------------+-------+
+| ``%Z``    | Time zone name (empty string   |       |
+|           | if the object is naive).       |       |
++-----------+--------------------------------+-------+
+| ``%%``    | A literal ``'%'`` character.   |       |
++-----------+--------------------------------+-------+
 
-Examples
---------
+Notes:
 
+(1)
+   When used with the :func:`strptime` function, the ``%f`` directive
+   accepts from one to six digits and zero pads on the right.  ``%f`` is
+   an extension to the set of format characters in the C standard (but
+   implemented separately in datetime objects, and therefore always
+   available).
 
-Creating Datetime Objects from Formatted Strings
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+(2)
+   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.
+
+(3)
+   The range really is ``0`` to ``61``; according to the Posix standard this
+   accounts for leap seconds and the (very rare) double leap seconds.
+   The :mod:`time` module may produce and does accept leap seconds since
+   it is based on the Posix standard, but the :mod:`datetime` module
+   does not accept leap seconds in :func:`strptime` input nor will it
+   produce them in :func:`strftime` output.
 
-The :class:`datetime` class does not directly support parsing formatted time
-strings.  You can use :func:`time.strptime` to do the parsing and create a
-:class:`datetime` object from the tuple it returns::
-
-   >>> 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)
+(4)
+   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.
 
+(5)
+   For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)``,
+   ``%z`` is replaced with the string ``'-0330'``.
