Skip to content

Commit

Permalink
pythongh-85453: Adapt datetime.rst to devguide recommendations for co…
Browse files Browse the repository at this point in the history 
…de snippets and variables (pythonGH-118068)

Also remove formatting from numeric literals.

(cherry picked from commit 809aa9a)

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>
  • Loading branch information
@uatach @serhiy-storchaka
@JelleZijlstra @erlend-aasland @miss-islington
4 people authored and miss-islington committed Apr 24, 2024
1 parent 0691bd8 commit eebf609
Showing 1 changed file with 45 additions and 45 deletions.
90 changes: 45 additions & 45 deletions Doc/library/datetime.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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):
Expand All @@ -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|
Expand All @@ -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 |
Expand All @@ -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
Expand Down Expand Up @@ -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) |
Expand All @@ -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.
Expand Down Expand Up @@ -652,7 +652,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()
Expand Down Expand Up @@ -972,8 +972,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``.


Expand Down Expand Up @@ -1130,8 +1130,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

Expand All @@ -1156,16 +1156,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.

Expand Down Expand Up @@ -1343,12 +1343,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()
Expand All @@ -1360,7 +1360,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.

Expand Down Expand Up @@ -1691,7 +1691,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:

Expand Down Expand Up @@ -1746,8 +1746,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

Expand Down Expand Up @@ -2036,7 +2036,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
Expand Down Expand Up @@ -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
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
Expand Down Expand Up @@ -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
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
Expand Down

0 comments on commit eebf609

Please sign in to comment.