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
|
||||
example, ::
|
||||
|
||||
>>> from datetime import timedelta
|
||||
>>> d = timedelta(microseconds=-1)
|
||||
>>> (d.days, d.seconds, d.microseconds)
|
||||
(-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
|
||||
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 @@ 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:
|
||||
|
||||
|
|
@ -922,6 +992,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:
|
||||
|
||||
|
|
@ -1067,6 +1237,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:
|
||||
|
||||
|
|
@ -1280,7 +1474,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:
|
||||
|
||||
|
|
@ -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
|
||||
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'``.
|
||||
|
|
|
|||
Loading…
Reference in New Issue