diff options
Diffstat (limited to 'Doc/library/datetime.rst')
| -rw-r--r-- | Doc/library/datetime.rst | 337 |
1 files changed, 298 insertions, 39 deletions
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'``. |