Mirror
/
cpython
mirror of https://github.com/python/cpython
4
1
Fork 0
Code Issues Releases Wiki Activity

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

Also remove formatting from numeric literals.

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:
edson duarte 2024-04-24 16:53:52 -03:00 committed by GitHub
parent 5865fa5f9b
commit 809aa9a682
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
1 changed files with 45 additions and 45 deletions
Show Stats 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
The smallest year number allowed in a :class:`date` or :class:`.datetime` object.
:const:`MINYEAR` is ``1``.
:const:`MINYEAR` is 1.
.. 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)
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.
Only *days*, *seconds* and *microseconds* are stored internally.
@ -280,7 +280,7 @@ Class attributes:
The smallest possible difference between non-equal :class:`timedelta` objects,
``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.
Instance attributes (read-only):
@ -302,26 +302,27 @@ Supported operations:
+--------------------------------+-----------------------------------------------+
| Operation | Result |
+================================+===============================================+
| ``t1 = t2 + t3`` | Sum of *t2* and *t3*. Afterwards *t1*-*t2* == |
| | *t3* and *t1*-*t3* == *t2* are true. (1) |
| ``t1 = t2 + t3`` | Sum of ``t2`` and ``t3``. |
| | Afterwards ``t1 - t2 == t3`` and |
| | ``t1 - t3 == t2`` are true. (1) |
+--------------------------------+-----------------------------------------------+
| ``t1 = t2 - t3`` | Difference of *t2* and *t3*. Afterwards *t1* |
| | == *t2* - *t3* and *t2* == *t1* + *t3* are |
| ``t1 = t2 - t3`` | Difference of ``t2`` and ``t3``. Afterwards |
| | ``t1 == t2 - t3`` and ``t2 == t1 + t3`` are |
| | true. (1)(6) |
+--------------------------------+-----------------------------------------------+
| ``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``. |
+--------------------------------+-----------------------------------------------+
| | In general, *t1* \* i == *t1* \* (i-1) + *t1* |
| | In general, ``t1 * i == t1 * (i-1) + t1`` |
| | is true. (1) |
+--------------------------------+-----------------------------------------------+
| ``t1 = t2 * f or t1 = f * t2`` | Delta multiplied by a float. The result is |
| | rounded to the nearest multiple of |
| | timedelta.resolution using round-half-to-even.|
+--------------------------------+-----------------------------------------------+
| ``f = t2 / t3`` | Division (3) of overall duration *t2* by |
| | interval unit *t3*. Returns a :class:`float` |
| ``f = t2 / t3`` | Division (3) of overall duration ``t2`` by |
| | interval unit ``t3``. Returns a :class:`float`|
| | object. |
+--------------------------------+-----------------------------------------------+
| ``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 |
| | same value. (2) |
+--------------------------------+-----------------------------------------------+
| ``-t1`` | equivalent to |
| | :class:`timedelta`\ (-*t1.days*, |
| | -*t1.seconds*, -*t1.microseconds*), |
| | and to *t1*\* -1. (1)(4) |
| ``-t1`` | Equivalent to ``timedelta(-t1.days, |
| | -t1.seconds*, -t1.microseconds)``, |
| | and to ``t1 * -1``. (1)(4) |
+--------------------------------+-----------------------------------------------+
| ``abs(t)`` | equivalent to +\ *t* when ``t.days >= 0``, |
| | and to -*t* when ``t.days < 0``. (2) |
| ``abs(t)`` | Equivalent to ``+t`` when ``t.days >= 0``, |
| | and to ``-t`` when ``t.days < 0``. (2) |
+--------------------------------+-----------------------------------------------+
| ``str(t)`` | Returns a string in the form |
| | ``[D day[s], ][H]H:MM:SS[.UUUUUU]``, where D |
@ -370,10 +370,10 @@ Notes:
This is exact and cannot overflow.
(3)
Division by 0 raises :exc:`ZeroDivisionError`.
Division by zero raises :exc:`ZeroDivisionError`.
(4)
-*timedelta.max* is not representable as a :class:`timedelta` object.
``-timedelta.max`` is not representable as a :class:`timedelta` object.
(5)
String representations of :class:`timedelta` objects are normalized
@ -583,10 +583,10 @@ Supported operations:
+-------------------------------+----------------------------------------------+
| Operation | Result |
+===============================+==============================================+
| ``date2 = date1 + timedelta`` | *date2* will be ``timedelta.days`` days |
| | after *date1*. (1) |
| ``date2 = date1 + timedelta`` | ``date2`` will be ``timedelta.days`` days |
| | after ``date1``. (1) |
+-------------------------------+----------------------------------------------+
| ``date2 = date1 - timedelta`` | Computes *date2* such that ``date2 + |
| ``date2 = date1 - timedelta`` | Computes ``date2`` such that ``date2 + |
| | timedelta == date1``. (2) |
+-------------------------------+----------------------------------------------+
| ``timedelta = date1 - date2`` | \(3) |
@ -613,8 +613,8 @@ Notes:
``timedelta.seconds`` and ``timedelta.microseconds`` are ignored.
(3)
This is exact, and cannot overflow. timedelta.seconds and
timedelta.microseconds are 0, and date2 + timedelta == date1 after.
This is exact, and cannot overflow. ``timedelta.seconds`` and
``timedelta.microseconds`` are 0, and ``date2 + timedelta == date1`` after.
(4)
:class:`date` objects are equal if they represent the same date.
@ -671,7 +671,7 @@ Instance methods:
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``
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()
@ -991,8 +991,8 @@ Other constructors, all class methods:
.. classmethod:: datetime.fromordinal(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
<= ordinal <= datetime.max.toordinal()``. The hour, minute, second and
where January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless
``1 <= ordinal <= datetime.max.toordinal()``. The hour, minute, second and
microsecond of the result are all 0, and :attr:`.tzinfo` is ``None``.
@ -1167,8 +1167,8 @@ Instance attributes (read-only):
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
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
time representation.
The values 0 and 1 represent, respectively, the earlier and later of the two
moments with the same wall time representation.
.. versionadded:: 3.6
@ -1193,16 +1193,16 @@ Supported operations:
+---------------------------------------+--------------------------------+
(1)
datetime2 is a duration of timedelta removed from datetime1, moving forward in
time if ``timedelta.days`` > 0, or backward if ``timedelta.days`` < 0. The
``datetime2`` is a duration of ``timedelta`` removed from ``datetime1``, moving forward in
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
datetime2 - datetime1 == timedelta after. :exc:`OverflowError` is raised if
datetime2.year would be smaller than :const:`MINYEAR` or larger than
``datetime2 - datetime1 == timedelta`` after. :exc:`OverflowError` is raised if
``datetime2.year`` would be smaller than :const:`MINYEAR` or larger than
:const:`MAXYEAR`. Note that no time zone adjustments are done even if the
input is an aware object.
(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
datetime, and no time zone adjustments are done even if the input is aware.
@ -1387,12 +1387,12 @@ Instance methods:
d.weekday(), yday, dst))
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
: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
non-zero value, :attr:`!tm_isdst` is set to ``1``; else :attr:`!tm_isdst` is
set to ``0``.
non-zero value, :attr:`!tm_isdst` is set to 1; else :attr:`!tm_isdst` is
set to 0.
.. method:: datetime.utctimetuple()
@ -1404,7 +1404,7 @@ Instance methods:
If *d* is aware, *d* is normalized to UTC time, by subtracting
``d.utcoffset()``, and a :class:`time.struct_time` for the
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
boundary.
@ -1735,7 +1735,7 @@ day, and subject to adjustment via a :class:`tzinfo` object.
* ``fold in [0, 1]``.
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:
@ -1790,8 +1790,8 @@ Instance attributes (read-only):
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
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
time representation.
The values 0 and 1 represent, respectively, the earlier and later of the two
moments with the same wall time representation.
.. versionadded:: 3.6
@ -2083,7 +2083,7 @@ Examples of working with a :class:`.time` object::
``tz.utcoffset(dt) - tz.dst(dt)``
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
only on geographic location. The implementation of :meth:`datetime.astimezone`
relies on this, but cannot detect violations; it's the programmer's
@ -2120,7 +2120,7 @@ Examples of working with a :class:`.time` object::
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,
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
a method rather than a fixed string primarily because some :class:`tzinfo`
subclasses will wish to return different names depending on the specific value
@ -2561,11 +2561,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
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
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
that can't be represented in the charset of the current locale is also