mirror of https://github.com/python/cpython
Add examples to the datetime documentation. Written for GHOP by "h4wk.cz".
This commit is contained in:
Georg Brandl
parent
dc563a655f
commit
e40a6a85ee
|
|
@ -163,6 +163,7 @@ dates or times.
|
||||||
Note that normalization of negative values may be surprising at first. For
|
Note that normalization of negative values may be surprising at first. For
|
||||||
example, ::
|
example, ::
|
||||||
|
|
||||||
|
>>> from datetime import timedelta
|
||||||
>>> d = timedelta(microseconds=-1)
|
>>> d = timedelta(microseconds=-1)
|
||||||
>>> (d.days, d.seconds, d.microseconds)
|
>>> (d.days, d.seconds, d.microseconds)
|
||||||
(-1, 86399, 999999)
|
(-1, 86399, 999999)
|
||||||
|
|
@ -266,6 +267,26 @@ comparison is ``==`` or ``!=``. The latter cases return :const:`False` or
|
||||||
efficient pickling, and in Boolean contexts, a :class:`timedelta` object is
|
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)``.
|
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:
|
.. _datetime-date:
|
||||||
|
|
||||||
|
|
@ -487,6 +508,55 @@ Instance methods:
|
||||||
Format codes referring to hours, minutes or seconds will see 0 values. See
|
Format codes referring to hours, minutes or seconds will see 0 values. See
|
||||||
section :ref:`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`::
|
||||||
|
|
||||||
|
>>> 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:
|
.. _datetime-datetime:
|
||||||
|
|
||||||
|
|
@ -922,6 +992,106 @@ Instance methods:
|
||||||
Return a string representing the date and time, controlled by an explicit format
|
Return a string representing the date and time, controlled by an explicit format
|
||||||
string. See section :ref:`strftime-behavior`.
|
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:
|
.. _datetime-time:
|
||||||
|
|
||||||
|
|
@ -1067,6 +1237,30 @@ Instance methods:
|
||||||
``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
|
``self.tzinfo.tzname(None)``, or raises an exception if the latter doesn't
|
||||||
return ``None`` or a string object.
|
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:
|
.. _datetime-tzinfo:
|
||||||
|
|
||||||
|
|
@ -1301,48 +1495,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
|
should not be used, as :class:`date` objects have no such values. If they're
|
||||||
used anyway, ``0`` is substituted for them.
|
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
|
The full set of format codes supported varies across platforms, because Python
|
||||||
calls the platform C library's :func:`strftime` function, and platform
|
calls the platform C library's :func:`strftime` function, and platform
|
||||||
variations are common. The documentation for Python's :mod:`time` module lists
|
variations are common.
|
||||||
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 following is a list of all the format codes that the C standard (1989
|
||||||
the C standard added additional format codes.
|
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
|
The exact range of years for which :meth:`strftime` works also varies across
|
||||||
platforms. Regardless of platform, years before 1900 cannot be used.
|
platforms. Regardless of platform, years before 1900 cannot be used.
|
||||||
|
|
||||||
.. % %% This example is obsolete, since strptime is now supported by datetime.
|
+-----------+--------------------------------+-------+
|
||||||
.. %
|
| Directive | Meaning | Notes |
|
||||||
.. % \subsection{Examples}
|
+===========+================================+=======+
|
||||||
.. %
|
| ``%a`` | Locale's abbreviated weekday | |
|
||||||
.. % \subsubsection{Creating Datetime Objects from Formatted Strings}
|
| | name. | |
|
||||||
.. %
|
+-----------+--------------------------------+-------+
|
||||||
.. % The \class{datetime} class does not directly support parsing formatted time
|
| ``%A`` | Locale's full weekday name. | |
|
||||||
.. % strings. You can use \function{time.strptime} to do the parsing and create
|
+-----------+--------------------------------+-------+
|
||||||
.. % a \class{datetime} object from the tuple it returns:
|
| ``%b`` | Locale's abbreviated month | |
|
||||||
.. %
|
| | name. | |
|
||||||
.. % \begin{verbatim}
|
+-----------+--------------------------------+-------+
|
||||||
.. % >>> s = "2005-12-06T12:13:14"
|
| ``%B`` | Locale's full month name. | |
|
||||||
.. % >>> from datetime import datetime
|
+-----------+--------------------------------+-------+
|
||||||
.. % >>> from time import strptime
|
| ``%c`` | Locale's appropriate date and | |
|
||||||
.. % >>> datetime(*strptime(s, "%Y-%m-%dT%H:%M:%S")[0:6])
|
| | time representation. | |
|
||||||
.. % datetime.datetime(2005, 12, 6, 12, 13, 14)
|
+-----------+--------------------------------+-------+
|
||||||
.. % \end{verbatim}
|
| ``%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'``.
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue