mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-09-27 18:59:43 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 13

[3.12] gh-85453: Adapt datetime.rst to devguide recommendations for code snippets and variables (GH-118068) (#118244)

Browse source 
Also remove formatting from numeric literals.

(cherry picked from commit 809aa9a682)

Co-authored-by: edson duarte <eduarte.uatach@gmail.com>
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>
Co-authored-by: Erlend E. Aasland <erlend@python.org>
This commit is contained in:
Miss Islington (bot) 2024-04-24 22:02:53 +02:00 • committed by GitHub
parent 0691bd860d
commit 0049e2bd38
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 45 additions and 45 deletions
Download patch file Download diff file Expand all files Collapse all files

90
Doc/library/datetime.rst
View file

@ -85,7 +85,7 @@ The :mod:`!datetime` module exports the following constants:
.. data:: MINYEAR .. data:: MINYEAR
The smallest year number allowed in a :class:`date` or :class:`.datetime` object. The smallest year number allowed in a :class:`date` or :class:`.datetime` object.
:const:`MINYEAR` is ``1``. :const:`MINYEAR` is 1.
.. data:: MAXYEAR .. data:: MAXYEAR
@ -207,7 +207,7 @@ A :class:`timedelta` object represents a duration, the difference between two
.. class:: timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0) .. class:: timedelta(days=0, seconds=0, microseconds=0, milliseconds=0, minutes=0, hours=0, weeks=0)
All arguments are optional and default to ``0``. Arguments may be integers All arguments are optional and default to 0. Arguments may be integers
or floats, and may be positive or negative. or floats, and may be positive or negative.
Only *days*, *seconds* and *microseconds* are stored internally. Only *days*, *seconds* and *microseconds* are stored internally.
@ -280,7 +280,7 @@ Class attributes:
The smallest possible difference between non-equal :class:`timedelta` objects, The smallest possible difference between non-equal :class:`timedelta` objects,
``timedelta(microseconds=1)``. ``timedelta(microseconds=1)``.
Note that, because of normalization, ``timedelta.max`` > ``-timedelta.min``. Note that, because of normalization, ``timedelta.max`` is greater than ``-timedelta.min``.
``-timedelta.max`` is not representable as a :class:`timedelta` object. ``-timedelta.max`` is not representable as a :class:`timedelta` object.
Instance attributes (read-only): Instance attributes (read-only):
@ -302,26 +302,27 @@ Supported operations:
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| Operation | Result | | Operation | Result |
+================================+===============================================+ +================================+===============================================+
| ``t1 = t2 + t3`` | Sum of *t2* and *t3*. Afterwards *t1*-*t2* == | | ``t1 = t2 + t3`` | Sum of ``t2`` and ``t3``. |
| | *t3* and *t1*-*t3* == *t2* are true. (1) | | | Afterwards ``t1 - t2 == t3`` and |
| | ``t1 - t3 == t2`` are true. (1) |
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| ``t1 = t2 - t3`` | Difference of *t2* and *t3*. Afterwards *t1* | | ``t1 = t2 - t3`` | Difference of ``t2`` and ``t3``. Afterwards |
| | == *t2* - *t3* and *t2* == *t1* + *t3* are | | | ``t1 == t2 - t3`` and ``t2 == t1 + t3`` are |
| | true. (1)(6) | | | true. (1)(6) |
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer. | | ``t1 = t2 * i or t1 = i * t2`` | Delta multiplied by an integer. |
| | Afterwards *t1* // i == *t2* is true, | | | Afterwards ``t1 // i == t2`` is true, |
| | provided ``i != 0``. | | | provided ``i != 0``. |
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| | In general, *t1* \* i == *t1* \* (i-1) + *t1* | | | In general, ``t1 * i == t1 * (i-1) + t1`` |
| | is true. (1) | | | is true. (1) |
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| ``t1 = t2 * f or t1 = f * t2`` | Delta multiplied by a float. The result is | | ``t1 = t2 * f or t1 = f * t2`` | Delta multiplied by a float. The result is |
| | rounded to the nearest multiple of | | | rounded to the nearest multiple of |
| | timedelta.resolution using round-half-to-even.| | | timedelta.resolution using round-half-to-even.|
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| ``f = t2 / t3`` | Division (3) of overall duration *t2* by | | ``f = t2 / t3`` | Division (3) of overall duration ``t2`` by |
| | interval unit *t3*. Returns a :class:`float` | | | interval unit ``t3``. Returns a :class:`float`|
| | object. | | | object. |
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| ``t1 = t2 / f or t1 = t2 / i`` | Delta divided by a float or an int. The result| | ``t1 = t2 / f or t1 = t2 / i`` | Delta divided by a float or an int. The result|
@ -343,13 +344,12 @@ Supported operations:
| ``+t1`` | Returns a :class:`timedelta` object with the | | ``+t1`` | Returns a :class:`timedelta` object with the |
| | same value. (2) | | | same value. (2) |
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| ``-t1`` | equivalent to | | ``-t1`` | Equivalent to ``timedelta(-t1.days, |
| | :class:`timedelta`\ (-*t1.days*, | | | -t1.seconds*, -t1.microseconds)``, |
| | -*t1.seconds*, -*t1.microseconds*), | | | and to ``t1 * -1``. (1)(4) |
| | and to *t1*\* -1. (1)(4) |
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| ``abs(t)`` | equivalent to +\ *t* when ``t.days >= 0``, | | ``abs(t)`` | Equivalent to ``+t`` when ``t.days >= 0``, |
| | and to -*t* when ``t.days < 0``. (2) | | | and to ``-t`` when ``t.days < 0``. (2) |
+--------------------------------+-----------------------------------------------+ +--------------------------------+-----------------------------------------------+
| ``str(t)`` | Returns a string in the form | | ``str(t)`` | Returns a string in the form |
| | ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D | | | ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D |
@ -370,10 +370,10 @@ Notes:
This is exact and cannot overflow. This is exact and cannot overflow.
(3) (3)
Division by 0 raises :exc:`ZeroDivisionError`. Division by zero raises :exc:`ZeroDivisionError`.
(4) (4)
-*timedelta.max* is not representable as a :class:`timedelta` object. ``-timedelta.max`` is not representable as a :class:`timedelta` object.
(5) (5)
String representations of :class:`timedelta` objects are normalized String representations of :class:`timedelta` objects are normalized
@ -583,10 +583,10 @@ Supported operations:
+-------------------------------+----------------------------------------------+ +-------------------------------+----------------------------------------------+
| Operation | Result | | Operation | Result |
+===============================+==============================================+ +===============================+==============================================+
| ``date2 = date1 + timedelta`` | *date2* will be ``timedelta.days`` days | | ``date2 = date1 + timedelta`` | ``date2`` will be ``timedelta.days`` days |
| | after *date1*. (1) | | | after ``date1``. (1) |
+-------------------------------+----------------------------------------------+ +-------------------------------+----------------------------------------------+
| ``date2 = date1 - timedelta`` | Computes *date2* such that ``date2 + | | ``date2 = date1 - timedelta`` | Computes ``date2`` such that ``date2 + |
| | timedelta == date1``. (2) | | | timedelta == date1``. (2) |
+-------------------------------+----------------------------------------------+ +-------------------------------+----------------------------------------------+
| ``timedelta = date1 - date2`` | \(3) | | ``timedelta = date1 - date2`` | \(3) |
@ -613,8 +613,8 @@ Notes:
``timedelta.seconds`` and ``timedelta.microseconds`` are ignored. ``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
(3) (3)
This is exact, and cannot overflow. timedelta.seconds and This is exact, and cannot overflow. ``timedelta.seconds`` and
timedelta.microseconds are 0, and date2 + timedelta == date1 after. ``timedelta.microseconds`` are 0, and ``date2 + timedelta == date1`` after.
(4) (4)
:class:`date` objects are equal if they represent the same date. :class:`date` objects are equal if they represent the same date.
@ -652,7 +652,7 @@ Instance methods:
time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1)) time.struct_time((d.year, d.month, d.day, 0, 0, 0, d.weekday(), yday, -1))
where ``yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` where ``yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1``
is the day number within the current year starting with ``1`` for January 1st. is the day number within the current year starting with 1 for January 1st.
.. method:: date.toordinal() .. method:: date.toordinal()
@ -972,8 +972,8 @@ Other constructors, all class methods:
.. classmethod:: datetime.fromordinal(ordinal) .. classmethod:: datetime.fromordinal(ordinal)
Return the :class:`.datetime` corresponding to the proleptic Gregorian ordinal, Return the :class:`.datetime` corresponding to the proleptic Gregorian ordinal,
where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless
<= ordinal <= datetime.max.toordinal()``. The hour, minute, second and ``1 <= ordinal <= datetime.max.toordinal()``. The hour, minute, second and
microsecond of the result are all 0, and :attr:`.tzinfo` is ``None``. microsecond of the result are all 0, and :attr:`.tzinfo` is ``None``.
@ -1130,8 +1130,8 @@ Instance attributes (read-only):
In ``[0, 1]``. Used to disambiguate wall times during a repeated interval. (A In ``[0, 1]``. Used to disambiguate wall times during a repeated interval. (A
repeated interval occurs when clocks are rolled back at the end of daylight saving repeated interval occurs when clocks are rolled back at the end of daylight saving
time or when the UTC offset for the current zone is decreased for political reasons.) time or when the UTC offset for the current zone is decreased for political reasons.)
The value 0 (1) represents the earlier (later) of the two moments with the same wall The values 0 and 1 represent, respectively, the earlier and later of the two
time representation. moments with the same wall time representation.
.. versionadded:: 3.6 .. versionadded:: 3.6
@ -1156,16 +1156,16 @@ Supported operations:
+---------------------------------------+--------------------------------+ +---------------------------------------+--------------------------------+
(1) (1)
datetime2 is a duration of timedelta removed from datetime1, moving forward in ``datetime2`` is a duration of ``timedelta`` removed from ``datetime1``, moving forward in
time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The time if ``timedelta.days > 0``, or backward if ``timedelta.days < 0``. The
result has the same :attr:`~.datetime.tzinfo` attribute as the input datetime, and result has the same :attr:`~.datetime.tzinfo` attribute as the input datetime, and
datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if ``datetime2 - datetime1 == timedelta`` after. :exc:`OverflowError` is raised if
datetime2.year would be smaller than :const:`MINYEAR` or larger than ``datetime2.year`` would be smaller than :const:`MINYEAR` or larger than
:const:`MAXYEAR`. Note that no time zone adjustments are done even if the :const:`MAXYEAR`. Note that no time zone adjustments are done even if the
input is an aware object. input is an aware object.
(2) (2)
Computes the datetime2 such that datetime2 + timedelta == datetime1. As for Computes the ``datetime2`` such that ``datetime2 + timedelta == datetime1``. As for
addition, the result has the same :attr:`~.datetime.tzinfo` attribute as the input addition, the result has the same :attr:`~.datetime.tzinfo` attribute as the input
datetime, and no time zone adjustments are done even if the input is aware. datetime, and no time zone adjustments are done even if the input is aware.
@ -1343,12 +1343,12 @@ Instance methods:
d.weekday(), yday, dst)) d.weekday(), yday, dst))
where ``yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1`` where ``yday = d.toordinal() - date(d.year, 1, 1).toordinal() + 1``
is the day number within the current year starting with ``1`` for January is the day number within the current year starting with 1 for January
1st. The :attr:`~time.struct_time.tm_isdst` flag of the result is set according to the 1st. The :attr:`~time.struct_time.tm_isdst` flag of the result is set according to the
:meth:`dst` method: :attr:`.tzinfo` is ``None`` or :meth:`dst` returns :meth:`dst` method: :attr:`.tzinfo` is ``None`` or :meth:`dst` returns
``None``, :attr:`!tm_isdst` is set to ``-1``; else if :meth:`dst` returns a ``None``, :attr:`!tm_isdst` is set to ``-1``; else if :meth:`dst` returns a
non-zero value, :attr:`!tm_isdst` is set to ``1``; else :attr:`!tm_isdst` is non-zero value, :attr:`!tm_isdst` is set to 1; else :attr:`!tm_isdst` is
set to ``0``. set to 0.
.. method:: datetime.utctimetuple() .. method:: datetime.utctimetuple()
@ -1360,7 +1360,7 @@ Instance methods:
If *d* is aware, *d* is normalized to UTC time, by subtracting If *d* is aware, *d* is normalized to UTC time, by subtracting
``d.utcoffset()``, and a :class:`time.struct_time` for the ``d.utcoffset()``, and a :class:`time.struct_time` for the
normalized time is returned. :attr:`!tm_isdst` is forced to 0. Note normalized time is returned. :attr:`!tm_isdst` is forced to 0. Note
that an :exc:`OverflowError` may be raised if *d*.year was that an :exc:`OverflowError` may be raised if ``d.year`` was
``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year ``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year
boundary. boundary.
@ -1691,7 +1691,7 @@ day, and subject to adjustment via a :class:`tzinfo` object.
* ``fold in [0, 1]``. * ``fold in [0, 1]``.
If an argument outside those ranges is given, :exc:`ValueError` is raised. All If an argument outside those ranges is given, :exc:`ValueError` is raised. All
default to ``0`` except *tzinfo*, which defaults to :const:`None`. default to 0 except *tzinfo*, which defaults to :const:`None`.
Class attributes: Class attributes:
@ -1746,8 +1746,8 @@ Instance attributes (read-only):
In ``[0, 1]``. Used to disambiguate wall times during a repeated interval. (A In ``[0, 1]``. Used to disambiguate wall times during a repeated interval. (A
repeated interval occurs when clocks are rolled back at the end of daylight saving repeated interval occurs when clocks are rolled back at the end of daylight saving
time or when the UTC offset for the current zone is decreased for political reasons.) time or when the UTC offset for the current zone is decreased for political reasons.)
The value 0 (1) represents the earlier (later) of the two moments with the same wall The values 0 and 1 represent, respectively, the earlier and later of the two
time representation. moments with the same wall time representation.
.. versionadded:: 3.6 .. versionadded:: 3.6
@ -2036,7 +2036,7 @@ Examples of working with a :class:`.time` object::
``tz.utcoffset(dt) - tz.dst(dt)`` ``tz.utcoffset(dt) - tz.dst(dt)``
must return the same result for every :class:`.datetime` *dt* with ``dt.tzinfo == must return the same result for every :class:`.datetime` *dt* with ``dt.tzinfo ==
tz`` For sane :class:`tzinfo` subclasses, this expression yields the time tz``. For sane :class:`tzinfo` subclasses, this expression yields the time
zone's "standard offset", which should not depend on the date or the time, but zone's "standard offset", which should not depend on the date or the time, but
only on geographic location. The implementation of :meth:`datetime.astimezone` only on geographic location. The implementation of :meth:`datetime.astimezone`
relies on this, but cannot detect violations; it's the programmer's relies on this, but cannot detect violations; it's the programmer's
@ -2073,7 +2073,7 @@ Examples of working with a :class:`.time` object::
Return the time zone name corresponding to the :class:`.datetime` object *dt*, as Return the time zone name corresponding to the :class:`.datetime` object *dt*, as
a string. Nothing about string names is defined by the :mod:`!datetime` module, a string. Nothing about string names is defined by the :mod:`!datetime` module,
and there's no requirement that it mean anything in particular. For example, and there's no requirement that it mean anything in particular. For example,
"GMT", "UTC", "-500", "-5:00", "EDT", "US/Eastern", "America/New York" are all ``"GMT"``, ``"UTC"``, ``"-500"``, ``"-5:00"``, ``"EDT"``, ``"US/Eastern"``, ``"America/New York"`` are all
valid replies. Return ``None`` if a string name isn't known. Note that this is valid replies. Return ``None`` if a string name isn't known. Note that this is
a method rather than a fixed string primarily because some :class:`tzinfo` a method rather than a fixed string primarily because some :class:`tzinfo`
subclasses will wish to return different names depending on the specific value subclasses will wish to return different names depending on the specific value
@ -2514,11 +2514,11 @@ information, which are supported in ``datetime.strptime`` but are discarded by
For :class:`.time` objects, the format codes for year, month, and day should not For :class:`.time` objects, the format codes for year, month, and day should not
be used, as :class:`!time` objects have no such values. If they're used anyway, be used, as :class:`!time` objects have no such values. If they're used anyway,
``1900`` is substituted for the year, and ``1`` for the month and day. ``1900`` is substituted for the year, and 1 for the month and day.
For :class:`date` objects, the format codes for hours, minutes, seconds, and For :class:`date` objects, the format codes for hours, minutes, seconds, and
microseconds should not be used, as :class:`date` objects have no such microseconds should not be used, as :class:`date` objects have no such
values. If they're used anyway, ``0`` is substituted for them. values. If they're used anyway, 0 is substituted for them.
For the same reason, handling of format strings containing Unicode code points For the same reason, handling of format strings containing Unicode code points
that can't be represented in the charset of the current locale is also that can't be represented in the charset of the current locale is also