Rietveld Code Review Tool
Help | Bug tracker | Discussion group | Source code | Sign in
(5)

Side by Side Diff: Doc/library/datetime.rst

Issue 10639: reindent.py converts newlines to platform default
Patch Set: Created 8 years, 8 months ago
Left:
Right:
Use n/p to move between diff chunks; N/P to move between comments. Please Sign in to add in-line comments.
Jump to:
View unified diff | Download patch
« no previous file with comments | « Doc/library/curses.rst ('k') | Doc/library/decimal.rst » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 :mod:`datetime` --- Basic date and time types 1 :mod:`datetime` --- Basic date and time types
2 ============================================= 2 =============================================
3 3
4 .. module:: datetime 4 .. module:: datetime
5 :synopsis: Basic date and time types. 5 :synopsis: Basic date and time types.
6 .. moduleauthor:: Tim Peters <tim@zope.com> 6 .. moduleauthor:: Tim Peters <tim@zope.com>
7 .. sectionauthor:: Tim Peters <tim@zope.com> 7 .. sectionauthor:: Tim Peters <tim@zope.com>
8 .. sectionauthor:: A.M. Kuchling <amk@amk.ca> 8 .. sectionauthor:: A.M. Kuchling <amk@amk.ca>
9 9
10 .. XXX what order should the types be discussed in? 10 .. XXX what order should the types be discussed in?
11 11
12 The :mod:`datetime` module supplies classes for manipulating dates and times in 12 The :mod:`datetime` module supplies classes for manipulating dates and times in
13 both simple and complex ways. While date and time arithmetic is supported, the 13 both simple and complex ways. While date and time arithmetic is supported, the
14 focus of the implementation is on efficient attribute extraction for output 14 focus of the implementation is on efficient member extraction for output
15 formatting and manipulation. For related 15 formatting and manipulation. For related
16 functionality, see also the :mod:`time` and :mod:`calendar` modules. 16 functionality, see also the :mod:`time` and :mod:`calendar` modules.
17 17
18 There are two kinds of date and time objects: "naive" and "aware". This 18 There are two kinds of date and time objects: "naive" and "aware". This
19 distinction refers to whether the object has any notion of time zone, daylight 19 distinction refers to whether the object has any notion of time zone, daylight
20 saving time, or other kind of algorithmic or political time adjustment. Whether 20 saving time, or other kind of algorithmic or political time adjustment. Whether
21 a naive :class:`datetime` object represents Coordinated Universal Time (UTC), 21 a naive :class:`datetime` object represents Coordinated Universal Time (UTC),
22 local time, or time in some other timezone is purely up to the program, just 22 local time, or time in some other timezone is purely up to the program, just
23 like it's up to the program whether a particular number represents metres, 23 like it's up to the program whether a particular number represents metres,
24 miles, or mass. Naive :class:`datetime` objects are easy to understand and to 24 miles, or mass. Naive :class:`datetime` objects are easy to understand and to
25 work with, at the cost of ignoring some aspects of reality. 25 work with, at the cost of ignoring some aspects of reality.
26 26
27 For applications requiring more, :class:`datetime` and :class:`time` objects 27 For applications requiring more, :class:`datetime` and :class:`time` objects
28 have an optional time zone information attribute, :attr:`tzinfo`, that can be 28 have an optional time zone information member, :attr:`tzinfo`, that can contain
29 set to an instance of a subclass of the abstract :class:`tzinfo` class. These 29 an instance of a subclass of the abstract :class:`tzinfo` class. These
30 :class:`tzinfo` objects capture information about the offset from UTC time, the 30 :class:`tzinfo` objects capture information about the offset from UTC time, the
31 time zone name, and whether Daylight Saving Time is in effect. Note that only 31 time zone name, and whether Daylight Saving Time is in effect. Note that only
32 one concrete :class:`tzinfo` class, the :class:`timezone` class, is supplied by the 32 one concrete :class:`tzinfo` class, the :class:`timezone` class, is supplied by the
33 :mod:`datetime` module. The :class:`timezone` class can reprsent simple 33 :mod:`datetime` module. The :class:`timezone` class can reprsent simple
34 timezones with fixed offset from UTC such as UTC itself or North American EST an d 34 timezones with fixed offset from UTC such as UTC itself or North American EST an d
35 EDT timezones. Supporting timezones at whatever level of detail is 35 EDT timezones. Supporting timezones at whatever level of detail is
36 required is up to the application. The rules for time adjustment across the 36 required is up to the application. The rules for time adjustment across the
37 world are more political than rational, change frequently, and there is no 37 world are more political than rational, change frequently, and there is no
38 standard suitable for every application aside from UTC. 38 standard suitable for every application aside from UTC.
39 39
(...skipping 452 matching lines...) Expand 10 before | Expand all | Expand 10 after
492 unless the comparison is ``==`` or ``!=``. The latter cases return 492 unless the comparison is ``==`` or ``!=``. The latter cases return
493 :const:`False` or :const:`True`, respectively. 493 :const:`False` or :const:`True`, respectively.
494 494
495 Dates can be used as dictionary keys. In Boolean contexts, all :class:`date` 495 Dates can be used as dictionary keys. In Boolean contexts, all :class:`date`
496 objects are considered to be true. 496 objects are considered to be true.
497 497
498 Instance methods: 498 Instance methods:
499 499
500 .. method:: date.replace(year, month, day) 500 .. method:: date.replace(year, month, day)
501 501
502 Return a date with the same value, except for those parameters given new 502 Return a date with the same value, except for those members given new values by
503 values by whichever keyword arguments are specified. For example, if ``d == 503 whichever keyword arguments are specified. For example, if ``d == date(2002,
504 date(2002, 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``. 504 12, 31)``, then ``d.replace(day=26) == date(2002, 12, 26)``.
505 505
506 506
507 .. method:: date.timetuple() 507 .. method:: date.timetuple()
508 508
509 Return a :class:`time.struct_time` such as returned by :func:`time.localtime` . 509 Return a :class:`time.struct_time` such as returned by :func:`time.localtime` .
510 The hours, minutes and seconds are 0, and the DST flag is -1. ``d.timetuple() `` 510 The hours, minutes and seconds are 0, and the DST flag is -1. ``d.timetuple() ``
511 is equivalent to ``time.struct_time((d.year, d.month, d.day, 0, 0, 0, 511 is equivalent to ``time.struct_time((d.year, d.month, d.day, 0, 0, 0,
512 d.weekday(), yday, -1))``, where ``yday = d.toordinal() - date(d.year, 1, 512 d.weekday(), yday, -1))``, where ``yday = d.toordinal() - date(d.year, 1,
513 1).toordinal() + 1`` is the day number within the current year starting with 513 1).toordinal() + 1`` is the day number within the current year starting with
514 ``1`` for January 1st. 514 ``1`` for January 1st.
(...skipping 226 matching lines...) Expand 10 before | Expand all | Expand 10 after
741 .. classmethod:: datetime.fromordinal(ordinal) 741 .. classmethod:: datetime.fromordinal(ordinal)
742 742
743 Return the :class:`datetime` corresponding to the proleptic Gregorian ordinal , 743 Return the :class:`datetime` corresponding to the proleptic Gregorian ordinal ,
744 where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ` `1 744 where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ` `1
745 <= ordinal <= datetime.max.toordinal()``. The hour, minute, second and 745 <= ordinal <= datetime.max.toordinal()``. The hour, minute, second and
746 microsecond of the result are all 0, and :attr:`tzinfo` is ``None``. 746 microsecond of the result are all 0, and :attr:`tzinfo` is ``None``.
747 747
748 748
749 .. classmethod:: datetime.combine(date, time) 749 .. classmethod:: datetime.combine(date, time)
750 750
751 Return a new :class:`datetime` object whose date components are equal to the 751 Return a new :class:`datetime` object whose date members are equal to the giv en
752 given :class:`date` object's, and whose time components and :attr:`tzinfo` 752 :class:`date` object's, and whose time and :attr:`tzinfo` members are equal t o
753 attributes are equal to the given :class:`time` object's. For any 753 the given :class:`time` object's. For any :class:`datetime` object *d*, ``d = =
754 :class:`datetime` object *d*, 754 datetime.combine(d.date(), d.timetz())``. If date is a :class:`datetime`
755 ``d == datetime.combine(d.date(), d.timetz())``. If date is a 755 object, its time and :attr:`tzinfo` members are ignored.
756 :class:`datetime` object, its time components and :attr:`tzinfo` attributes
757 are ignored.
758 756
759 757
760 .. classmethod:: datetime.strptime(date_string, format) 758 .. classmethod:: datetime.strptime(date_string, format)
761 759
762 Return a :class:`datetime` corresponding to *date_string*, parsed according t o 760 Return a :class:`datetime` corresponding to *date_string*, parsed according t o
763 *format*. This is equivalent to ``datetime(*(time.strptime(date_string, 761 *format*. This is equivalent to ``datetime(*(time.strptime(date_string,
764 format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format 762 format)[0:6]))``. :exc:`ValueError` is raised if the date_string and format
765 can't be parsed by :func:`time.strptime` or if it returns a value which isn't a 763 can't be parsed by :func:`time.strptime` or if it returns a value which isn't a
766 time tuple. See section :ref:`strftime-strptime-behavior`. 764 time tuple. See section :ref:`strftime-strptime-behavior`.
767 765
(...skipping 73 matching lines...) Expand 10 before | Expand all | Expand 10 after
841 +---------------------------------------+-------------------------------+ 839 +---------------------------------------+-------------------------------+
842 | ``timedelta = datetime1 - datetime2`` | \(3) | 840 | ``timedelta = datetime1 - datetime2`` | \(3) |
843 +---------------------------------------+-------------------------------+ 841 +---------------------------------------+-------------------------------+
844 | ``datetime1 < datetime2`` | Compares :class:`datetime` to | 842 | ``datetime1 < datetime2`` | Compares :class:`datetime` to |
845 | | :class:`datetime`. (4) | 843 | | :class:`datetime`. (4) |
846 +---------------------------------------+-------------------------------+ 844 +---------------------------------------+-------------------------------+
847 845
848 (1) 846 (1)
849 datetime2 is a duration of timedelta removed from datetime1, moving forward i n 847 datetime2 is a duration of timedelta removed from datetime1, moving forward i n
850 time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The 848 time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The
851 result has the same :attr:`tzinfo` attribute as the input datetime, and 849 result has the same :attr:`tzinfo` member as the input datetime, and datetime 2 -
852 datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if 850 datetime1 == timedelta after. :exc:`OverflowError` is raised if datetime2.yea r
853 datetime2.year would be smaller than :const:`MINYEAR` or larger than 851 would be smaller than :const:`MINYEAR` or larger than :const:`MAXYEAR`. Note
854 :const:`MAXYEAR`. Note that no time zone adjustments are done even if the 852 that no time zone adjustments are done even if the input is an aware object.
855 input is an aware object.
856 853
857 (2) 854 (2)
858 Computes the datetime2 such that datetime2 + timedelta == datetime1. As for 855 Computes the datetime2 such that datetime2 + timedelta == datetime1. As for
859 addition, the result has the same :attr:`tzinfo` attribute as the input 856 addition, the result has the same :attr:`tzinfo` member as the input datetime ,
860 datetime, and no time zone adjustments are done even if the input is aware. 857 and no time zone adjustments are done even if the input is aware. This isn't
861 This isn't quite equivalent to datetime1 + (-timedelta), because -timedelta 858 quite equivalent to datetime1 + (-timedelta), because -timedelta in isolation
862 in isolation can overflow in cases where datetime1 - timedelta does not. 859 can overflow in cases where datetime1 - timedelta does not.
863 860
864 (3) 861 (3)
865 Subtraction of a :class:`datetime` from a :class:`datetime` is defined only i f 862 Subtraction of a :class:`datetime` from a :class:`datetime` is defined only i f
866 both operands are naive, or if both are aware. If one is aware and the other is 863 both operands are naive, or if both are aware. If one is aware and the other is
867 naive, :exc:`TypeError` is raised. 864 naive, :exc:`TypeError` is raised.
868 865
869 If both are naive, or both are aware and have the same :attr:`tzinfo` attribu te, 866 If both are naive, or both are aware and have the same :attr:`tzinfo` member,
870 the :attr:`tzinfo` attributes are ignored, and the result is a :class:`timede lta` 867 the :attr:`tzinfo` members are ignored, and the result is a :class:`timedelta `
871 object *t* such that ``datetime2 + t == datetime1``. No time zone adjustment s 868 object *t* such that ``datetime2 + t == datetime1``. No time zone adjustment s
872 are done in this case. 869 are done in this case.
873 870
874 If both are aware and have different :attr:`tzinfo` attributes, ``a-b`` acts 871 If both are aware and have different :attr:`tzinfo` members, ``a-b`` acts as if
875 as if *a* and *b* were first converted to naive UTC datetimes first. The 872 *a* and *b* were first converted to naive UTC datetimes first. The result is
876 result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None ) 873 ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) -
877 - b.utcoffset())`` except that the implementation never overflows. 874 b.utcoffset())`` except that the implementation never overflows.
878 875
879 (4) 876 (4)
880 *datetime1* is considered less than *datetime2* when *datetime1* precedes 877 *datetime1* is considered less than *datetime2* when *datetime1* precedes
881 *datetime2* in time. 878 *datetime2* in time.
882 879
883 If one comparand is naive and the other is aware, :exc:`TypeError` is raised. 880 If one comparand is naive and the other is aware, :exc:`TypeError` is raised.
884 If both comparands are aware, and have the same :attr:`tzinfo` attribute, the 881 If both comparands are aware, and have the same :attr:`tzinfo` member, the
885 common :attr:`tzinfo` attribute is ignored and the base datetimes are 882 common :attr:`tzinfo` member is ignored and the base datetimes are compared. If
886 compared. If both comparands are aware and have different :attr:`tzinfo` 883 both comparands are aware and have different :attr:`tzinfo` members, the
887 attributes, the comparands are first adjusted by subtracting their UTC 884 comparands are first adjusted by subtracting their UTC offsets (obtained from
888 offsets (obtained from ``self.utcoffset()``). 885 ``self.utcoffset()``).
889 886
890 .. note:: 887 .. note::
891 888
892 In order to stop comparison from falling back to the default scheme of com paring 889 In order to stop comparison from falling back to the default scheme of com paring
893 object addresses, datetime comparison normally raises :exc:`TypeError` if the 890 object addresses, datetime comparison normally raises :exc:`TypeError` if the
894 other comparand isn't also a :class:`datetime` object. However, 891 other comparand isn't also a :class:`datetime` object. However,
895 ``NotImplemented`` is returned instead if the other comparand has a 892 ``NotImplemented`` is returned instead if the other comparand has a
896 :meth:`timetuple` attribute. This hook gives other kinds of date objects a 893 :meth:`timetuple` attribute. This hook gives other kinds of date objects a
897 chance at implementing mixed-type comparison. If not, when a :class:`date time` 894 chance at implementing mixed-type comparison. If not, when a :class:`date time`
898 object is compared to an object of a different type, :exc:`TypeError` is r aised 895 object is compared to an object of a different type, :exc:`TypeError` is r aised
(...skipping 12 matching lines...) Expand all
911 908
912 .. method:: datetime.time() 909 .. method:: datetime.time()
913 910
914 Return :class:`time` object with same hour, minute, second and microsecond. 911 Return :class:`time` object with same hour, minute, second and microsecond.
915 :attr:`tzinfo` is ``None``. See also method :meth:`timetz`. 912 :attr:`tzinfo` is ``None``. See also method :meth:`timetz`.
916 913
917 914
918 .. method:: datetime.timetz() 915 .. method:: datetime.timetz()
919 916
920 Return :class:`time` object with same hour, minute, second, microsecond, and 917 Return :class:`time` object with same hour, minute, second, microsecond, and
921 tzinfo attributes. See also method :meth:`time`. 918 tzinfo members. See also method :meth:`time`.
922 919
923 920
924 .. method:: datetime.replace([year[, month[, day[, hour[, minute[, second[, micr osecond[, tzinfo]]]]]]]]) 921 .. method:: datetime.replace([year[, month[, day[, hour[, minute[, second[, micr osecond[, tzinfo]]]]]]]])
925 922
926 Return a datetime with the same attributes, except for those attributes given 923 Return a datetime with the same members, except for those members given new
927 new values by whichever keyword arguments are specified. Note that 924 values by whichever keyword arguments are specified. Note that ``tzinfo=None ``
928 ``tzinfo=None`` can be specified to create a naive datetime from an aware 925 can be specified to create a naive datetime from an aware datetime with no
929 datetime with no conversion of date and time data. 926 conversion of date and time members.
930 927
931 928
932 .. method:: datetime.astimezone(tz) 929 .. method:: datetime.astimezone(tz)
933 930
934 Return a :class:`datetime` object with new :attr:`tzinfo` attribute *tz*, 931 Return a :class:`datetime` object with new :attr:`tzinfo` member *tz*, adjust ing
935 adjusting the date and time data so the result is the same UTC time as 932 the date and time members so the result is the same UTC time as *self*, but i n
936 *self*, but in *tz*'s local time. 933 *tz*'s local time.
937 934
938 *tz* must be an instance of a :class:`tzinfo` subclass, and its 935 *tz* must be an instance of a :class:`tzinfo` subclass, and its
939 :meth:`utcoffset` and :meth:`dst` methods must not return ``None``. *self* m ust 936 :meth:`utcoffset` and :meth:`dst` methods must not return ``None``. *self* m ust
940 be aware (``self.tzinfo`` must not be ``None``, and ``self.utcoffset()`` must 937 be aware (``self.tzinfo`` must not be ``None``, and ``self.utcoffset()`` must
941 not return ``None``). 938 not return ``None``).
942 939
943 If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*: no 940 If ``self.tzinfo`` is *tz*, ``self.astimezone(tz)`` is equal to *self*: no
944 adjustment of date or time data is performed. Else the result is local 941 adjustment of date or time members is performed. Else the result is local tim e
945 time in time zone *tz*, representing the same UTC time as *self*: after 942 in time zone *tz*, representing the same UTC time as *self*: after ``astz =
946 ``astz = dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have 943 dt.astimezone(tz)``, ``astz - astz.utcoffset()`` will usually have the same d ate
947 the same date and time data as ``dt - dt.utcoffset()``. The discussion 944 and time members as ``dt - dt.utcoffset()``. The discussion of class
948 of class :class:`tzinfo` explains the cases at Daylight Saving Time transitio n 945 :class:`tzinfo` explains the cases at Daylight Saving Time transition boundar ies
949 boundaries where this cannot be achieved (an issue only if *tz* models both 946 where this cannot be achieved (an issue only if *tz* models both standard and
950 standard and daylight time). 947 daylight time).
951 948
952 If you merely want to attach a time zone object *tz* to a datetime *dt* witho ut 949 If you merely want to attach a time zone object *tz* to a datetime *dt* witho ut
953 adjustment of date and time data, use ``dt.replace(tzinfo=tz)``. If you 950 adjustment of date and time members, use ``dt.replace(tzinfo=tz)``. If you
954 merely want to remove the time zone object from an aware datetime *dt* withou t 951 merely want to remove the time zone object from an aware datetime *dt* withou t
955 conversion of date and time data, use ``dt.replace(tzinfo=None)``. 952 conversion of date and time members, use ``dt.replace(tzinfo=None)``.
956 953
957 Note that the default :meth:`tzinfo.fromutc` method can be overridden in a 954 Note that the default :meth:`tzinfo.fromutc` method can be overridden in a
958 :class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`. 955 :class:`tzinfo` subclass to affect the result returned by :meth:`astimezone`.
959 Ignoring error cases, :meth:`astimezone` acts like:: 956 Ignoring error cases, :meth:`astimezone` acts like::
960 957
961 def astimezone(self, tz): 958 def astimezone(self, tz):
962 if self.tzinfo is tz: 959 if self.tzinfo is tz:
963 return self 960 return self
964 # Convert self to UTC, and attach the new time zone object. 961 # Convert self to UTC, and attach the new time zone object.
965 utc = (self - self.utcoffset()).replace(tzinfo=tz) 962 utc = (self - self.utcoffset()).replace(tzinfo=tz)
(...skipping 290 matching lines...) Expand 10 before | Expand all | Expand 10 after
1256 1253
1257 The object passed as the tzinfo argument to the :class:`time` constructor, or 1254 The object passed as the tzinfo argument to the :class:`time` constructor, or
1258 ``None`` if none was passed. 1255 ``None`` if none was passed.
1259 1256
1260 1257
1261 Supported operations: 1258 Supported operations:
1262 1259
1263 * comparison of :class:`time` to :class:`time`, where *a* is considered less 1260 * comparison of :class:`time` to :class:`time`, where *a* is considered less
1264 than *b* when *a* precedes *b* in time. If one comparand is naive and the oth er 1261 than *b* when *a* precedes *b* in time. If one comparand is naive and the oth er
1265 is aware, :exc:`TypeError` is raised. If both comparands are aware, and have 1262 is aware, :exc:`TypeError` is raised. If both comparands are aware, and have
1266 the same :attr:`tzinfo` attribute, the common :attr:`tzinfo` attribute is 1263 the same :attr:`tzinfo` member, the common :attr:`tzinfo` member is ignored an d
1267 ignored and the base times are compared. If both comparands are aware and 1264 the base times are compared. If both comparands are aware and have different
1268 have different :attr:`tzinfo` attributes, the comparands are first adjusted by 1265 :attr:`tzinfo` members, the comparands are first adjusted by subtracting their
1269 subtracting their UTC offsets (obtained from ``self.utcoffset()``). In order 1266 UTC offsets (obtained from ``self.utcoffset()``). In order to stop mixed-type
1270 to stop mixed-type comparisons from falling back to the default comparison by 1267 comparisons from falling back to the default comparison by object address, whe n
1271 object address, when a :class:`time` object is compared to an object of a 1268 a :class:`time` object is compared to an object of a different type,
1272 different type, :exc:`TypeError` is raised unless the comparison is ``==`` or 1269 :exc:`TypeError` is raised unless the comparison is ``==`` or ``!=``. The
1273 ``!=``. The latter cases return :const:`False` or :const:`True`, respectively . 1270 latter cases return :const:`False` or :const:`True`, respectively.
1274 1271
1275 * hash, use as dict key 1272 * hash, use as dict key
1276 1273
1277 * efficient pickling 1274 * efficient pickling
1278 1275
1279 * in Boolean contexts, a :class:`time` object is considered to be true if and 1276 * in Boolean contexts, a :class:`time` object is considered to be true if and
1280 only if, after converting it to minutes and subtracting :meth:`utcoffset` (or 1277 only if, after converting it to minutes and subtracting :meth:`utcoffset` (or
1281 ``0`` if that's ``None``), the result is non-zero. 1278 ``0`` if that's ``None``), the result is non-zero.
1282 1279
1283 1280
1284 Instance methods: 1281 Instance methods:
1285 1282
1286 .. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]]) 1283 .. method:: time.replace([hour[, minute[, second[, microsecond[, tzinfo]]]]])
1287 1284
1288 Return a :class:`time` with the same value, except for those attributes given 1285 Return a :class:`time` with the same value, except for those members given ne w
1289 new values by whichever keyword arguments are specified. Note that 1286 values by whichever keyword arguments are specified. Note that ``tzinfo=None ``
1290 ``tzinfo=None`` can be specified to create a naive :class:`time` from an 1287 can be specified to create a naive :class:`time` from an aware :class:`time`,
1291 aware :class:`time`, without conversion of the time data. 1288 without conversion of the time members.
1292 1289
1293 1290
1294 .. method:: time.isoformat() 1291 .. method:: time.isoformat()
1295 1292
1296 Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, if 1293 Return a string representing the time in ISO 8601 format, HH:MM:SS.mmmmmm or, if
1297 self.microsecond is 0, HH:MM:SS If :meth:`utcoffset` does not return ``None`` , a 1294 self.microsecond is 0, HH:MM:SS If :meth:`utcoffset` does not return ``None`` , a
1298 6-character string is appended, giving the UTC offset in (signed) hours and 1295 6-character string is appended, giving the UTC offset in (signed) hours and
1299 minutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM 1296 minutes: HH:MM:SS.mmmmmm+HH:MM or, if self.microsecond is 0, HH:MM:SS+HH:MM
1300 1297
1301 1298
(...skipping 64 matching lines...) Expand 10 before | Expand all | Expand 10 after
1366 :class:`tzinfo` is an abstract base class, meaning that this class should not be 1363 :class:`tzinfo` is an abstract base class, meaning that this class should not be
1367 instantiated directly. You need to derive a concrete subclass, and (at least) 1364 instantiated directly. You need to derive a concrete subclass, and (at least)
1368 supply implementations of the standard :class:`tzinfo` methods needed by the 1365 supply implementations of the standard :class:`tzinfo` methods needed by the
1369 :class:`datetime` methods you use. The :mod:`datetime` module supplies 1366 :class:`datetime` methods you use. The :mod:`datetime` module supplies
1370 a simple concrete subclass of :class:`tzinfo` :class:`timezone` which can reprse nt 1367 a simple concrete subclass of :class:`tzinfo` :class:`timezone` which can reprse nt
1371 timezones with fixed offset from UTC such as UTC itself or North American EST an d 1368 timezones with fixed offset from UTC such as UTC itself or North American EST an d
1372 EDT. 1369 EDT.
1373 1370
1374 An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the 1371 An instance of (a concrete subclass of) :class:`tzinfo` can be passed to the
1375 constructors for :class:`datetime` and :class:`time` objects. The latter objects 1372 constructors for :class:`datetime` and :class:`time` objects. The latter objects
1376 view their attributes as being in local time, and the :class:`tzinfo` object 1373 view their members as being in local time, and the :class:`tzinfo` object
1377 supports methods revealing offset of local time from UTC, the name of the time 1374 supports methods revealing offset of local time from UTC, the name of the time
1378 zone, and DST offset, all relative to a date or time object passed to them. 1375 zone, and DST offset, all relative to a date or time object passed to them.
1379 1376
1380 Special requirement for pickling: A :class:`tzinfo` subclass must have an 1377 Special requirement for pickling: A :class:`tzinfo` subclass must have an
1381 :meth:`__init__` method that can be called with no arguments, else it can be 1378 :meth:`__init__` method that can be called with no arguments, else it can be
1382 pickled but possibly not unpickled again. This is a technical requirement that 1379 pickled but possibly not unpickled again. This is a technical requirement that
1383 may be relaxed in the future. 1380 may be relaxed in the future.
1384 1381
1385 A concrete subclass of :class:`tzinfo` may need to implement the following 1382 A concrete subclass of :class:`tzinfo` may need to implement the following
1386 methods. Exactly which methods are needed depends on the uses made of aware 1383 methods. Exactly which methods are needed depends on the uses made of aware
(...skipping 24 matching lines...) Expand all
1411 1408
1412 .. method:: tzinfo.dst(dt) 1409 .. method:: tzinfo.dst(dt)
1413 1410
1414 Return the daylight saving time (DST) adjustment, in minutes east of UTC, or 1411 Return the daylight saving time (DST) adjustment, in minutes east of UTC, or
1415 ``None`` if DST information isn't known. Return ``timedelta(0)`` if DST is n ot 1412 ``None`` if DST information isn't known. Return ``timedelta(0)`` if DST is n ot
1416 in effect. If DST is in effect, return the offset as a :class:`timedelta` obj ect 1413 in effect. If DST is in effect, return the offset as a :class:`timedelta` obj ect
1417 (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has 1414 (see :meth:`utcoffset` for details). Note that DST offset, if applicable, has
1418 already been added to the UTC offset returned by :meth:`utcoffset`, so there' s 1415 already been added to the UTC offset returned by :meth:`utcoffset`, so there' s
1419 no need to consult :meth:`dst` unless you're interested in obtaining DST info 1416 no need to consult :meth:`dst` unless you're interested in obtaining DST info
1420 separately. For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo` 1417 separately. For example, :meth:`datetime.timetuple` calls its :attr:`tzinfo`
1421 attribute's :meth:`dst` method to determine how the :attr:`tm_isdst` flag 1418 member's :meth:`dst` method to determine how the :attr:`tm_isdst` flag should be
1422 should be set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for 1419 set, and :meth:`tzinfo.fromutc` calls :meth:`dst` to account for DST changes
1423 DST changes when crossing time zones. 1420 when crossing time zones.
1424 1421
1425 An instance *tz* of a :class:`tzinfo` subclass that models both standard and 1422 An instance *tz* of a :class:`tzinfo` subclass that models both standard and
1426 daylight times must be consistent in this sense: 1423 daylight times must be consistent in this sense:
1427 1424
1428 ``tz.utcoffset(dt) - tz.dst(dt)`` 1425 ``tz.utcoffset(dt) - tz.dst(dt)``
1429 1426
1430 must return the same result for every :class:`datetime` *dt* with ``dt.tzinfo == 1427 must return the same result for every :class:`datetime` *dt* with ``dt.tzinfo ==
1431 tz`` For sane :class:`tzinfo` subclasses, this expression yields the time 1428 tz`` For sane :class:`tzinfo` subclasses, this expression yields the time
1432 zone's "standard offset", which should not depend on the date or the time, bu t 1429 zone's "standard offset", which should not depend on the date or the time, bu t
1433 only on geographic location. The implementation of :meth:`datetime.astimezon e` 1430 only on geographic location. The implementation of :meth:`datetime.astimezon e`
(...skipping 54 matching lines...) Expand 10 before | Expand all | Expand 10 after
1488 method, ``dt.tzinfo`` is the same object as *self*. :class:`tzinfo` methods can 1485 method, ``dt.tzinfo`` is the same object as *self*. :class:`tzinfo` methods can
1489 rely on this, unless user code calls :class:`tzinfo` methods directly. The 1486 rely on this, unless user code calls :class:`tzinfo` methods directly. The
1490 intent is that the :class:`tzinfo` methods interpret *dt* as being in local 1487 intent is that the :class:`tzinfo` methods interpret *dt* as being in local
1491 time, and not need worry about objects in other timezones. 1488 time, and not need worry about objects in other timezones.
1492 1489
1493 There is one more :class:`tzinfo` method that a subclass may wish to override: 1490 There is one more :class:`tzinfo` method that a subclass may wish to override:
1494 1491
1495 1492
1496 .. method:: tzinfo.fromutc(dt) 1493 .. method:: tzinfo.fromutc(dt)
1497 1494
1498 This is called from the default :class:`datetime.astimezone()` 1495 This is called from the default :class:`datetime.astimezone()` implementation .
1499 implementation. When called from that, ``dt.tzinfo`` is *self*, and *dt*'s 1496 When called from that, ``dt.tzinfo`` is *self*, and *dt*'s date and time memb ers
1500 date and time data are to be viewed as expressing a UTC time. The purpose 1497 are to be viewed as expressing a UTC time. The purpose of :meth:`fromutc` is to
1501 of :meth:`fromutc` is to adjust the date and time data, returning an 1498 adjust the date and time members, returning an equivalent datetime in *self*' s
1502 equivalent datetime in *self*'s local time. 1499 local time.
1503 1500
1504 Most :class:`tzinfo` subclasses should be able to inherit the default 1501 Most :class:`tzinfo` subclasses should be able to inherit the default
1505 :meth:`fromutc` implementation without problems. It's strong enough to handl e 1502 :meth:`fromutc` implementation without problems. It's strong enough to handl e
1506 fixed-offset time zones, and time zones accounting for both standard and 1503 fixed-offset time zones, and time zones accounting for both standard and
1507 daylight time, and the latter even if the DST transition times differ in 1504 daylight time, and the latter even if the DST transition times differ in
1508 different years. An example of a time zone the default :meth:`fromutc` 1505 different years. An example of a time zone the default :meth:`fromutc`
1509 implementation may not handle correctly in all cases is one where the standar d 1506 implementation may not handle correctly in all cases is one where the standar d
1510 offset (from UTC) depends on the specific date and time passed, which can hap pen 1507 offset (from UTC) depends on the specific date and time passed, which can hap pen
1511 for political reasons. The default implementations of :meth:`astimezone` and 1508 for political reasons. The default implementations of :meth:`astimezone` and
1512 :meth:`fromutc` may not produce the result you want if the result is one of t he 1509 :meth:`fromutc` may not produce the result you want if the result is one of t he
(...skipping 288 matching lines...) Expand 10 before | Expand all | Expand 10 after
1801 years >= 1000. 1798 years >= 1000.
1802 1799
1803 (6) 1800 (6)
1804 For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)` `, 1801 For example, if :meth:`utcoffset` returns ``timedelta(hours=-3, minutes=-30)` `,
1805 ``%z`` is replaced with the string ``'-0330'``. 1802 ``%z`` is replaced with the string ``'-0330'``.
1806 1803
1807 .. versionchanged:: 3.2 1804 .. versionchanged:: 3.2
1808 When the ``%z`` directive is provided to the :meth:`strptime` method, an 1805 When the ``%z`` directive is provided to the :meth:`strptime` method, an
1809 aware :class:`datetime` object will be produced. The ``tzinfo`` of the 1806 aware :class:`datetime` object will be produced. The ``tzinfo`` of the
1810 result will be set to a :class:`timezone` instance. 1807 result will be set to a :class:`timezone` instance.
OLDNEW
« no previous file with comments | « Doc/library/curses.rst ('k') | Doc/library/decimal.rst » ('j') | no next file with comments »

RSS Feeds Recent Issues | This issue
This is Rietveld 894c83f36cb7+