[Python-checkins] r59416 - python/trunk/Doc/library/datetime.rst
georg.brandl
python-checkins at python.org
Sat Dec 8 12:23:14 CET 2007
Author: georg.brandl
Date: Sat Dec 8 12:23:13 2007
New Revision: 59416
Modified:
python/trunk/Doc/library/datetime.rst
Log:
Add examples to the datetime documentation. Written for GHOP by "h4wk.cz".
Modified: python/trunk/Doc/library/datetime.rst
==============================================================================
--- python/trunk/Doc/library/datetime.rst (original)
+++ python/trunk/Doc/library/datetime.rst Sat Dec 8 12:23:13 2007
@@ -163,6 +163,7 @@
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)
@@ -266,6 +267,26 @@
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:
@@ -487,6 +508,55 @@
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:
@@ -922,6 +992,106 @@
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:
@@ -1067,6 +1237,30 @@
``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:
@@ -1280,7 +1474,7 @@
: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:
@@ -1301,48 +1495,113 @@
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'``.
More information about the Python-checkins
mailing list