From 562d43e580b4a5b5e65a5d5830ae76ef7066673d Mon Sep 17 00:00:00 2001 From: edson duarte Date: Thu, 18 Apr 2024 19:33:37 -0300 Subject: [PATCH 01/11] Improve backquotes, italics and timedelta read-only instance attributes --- Doc/library/datetime.rst | 149 ++++++++++++++++++++------------------- 1 file changed, 77 insertions(+), 72 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index e8bd51ba20802e..b30421048216bf 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -114,7 +114,7 @@ Available Types :noindex: An idealized time, independent of any particular day, assuming that every day - has exactly 24\*60\*60 seconds. (There is no notion of "leap seconds" here.) + has exactly ``24 * 60 * 60`` seconds. (There is no notion of "leap seconds" here.) Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`, and :attr:`.tzinfo`. @@ -213,10 +213,10 @@ A :class:`timedelta` object represents a duration, the difference between two Only *days*, *seconds* and *microseconds* are stored internally. Arguments are converted to those units: - * A millisecond is converted to 1000 microseconds. - * A minute is converted to 60 seconds. - * An hour is converted to 3600 seconds. - * A week is converted to 7 days. + * A *millisecond* is converted to ``1000`` *microseconds*. + * A *minute* is converted to ``60`` *seconds*. + * An *hour* is converted to ``3600`` *seconds*. + * A *week* is converted to ``7`` *days*. and days, seconds and microseconds are then normalized so that the representation is unique, with @@ -280,20 +280,26 @@ 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 > -timedelta.min`` is true. ``-timedelta.max`` is not representable as a :class:`timedelta` object. Instance attributes (read-only): -+------------------+--------------------------------------------+ -| Attribute | Value | -+==================+============================================+ -| ``days`` | Between -999999999 and 999999999 inclusive | -+------------------+--------------------------------------------+ -| ``seconds`` | Between 0 and 86399 inclusive | -+------------------+--------------------------------------------+ -| ``microseconds`` | Between 0 and 999999 inclusive | -+------------------+--------------------------------------------+ + +.. attribute:: timedelta.days + + Between ``-999999999`` and ``999999999`` inclusive. + + +.. attribute:: timedelta.seconds + + Between ``0`` and ``86399`` inclusive. + + +.. attribute:: timedelta.microseconds + + Between ``0`` and ``999999`` inclusive. + Supported operations: @@ -302,18 +308,18 @@ 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 | @@ -343,10 +349,9 @@ 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) | @@ -370,10 +375,10 @@ Notes: This is exact and cannot overflow. (3) - Division by 0 raises :exc:`ZeroDivisionError`. + Division by ``0`` 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 @@ -503,7 +508,7 @@ Other constructors, all class methods: .. classmethod:: date.fromordinal(ordinal) Return the date corresponding to the proleptic Gregorian ordinal, where - January 1 of year 1 has ordinal 1. + January 1 of year 1 has ordinal ``1``. :exc:`ValueError` is raised unless ``1 <= ordinal <= date.max.toordinal()``. For any date *d*, @@ -570,12 +575,12 @@ Instance attributes (read-only): .. attribute:: date.month - Between 1 and 12 inclusive. + Between ``1`` and ``12`` inclusive. .. attribute:: date.day - Between 1 and the number of days in the given month of the given year. + Between ``1`` and the number of days in the given month of the given year. Supported operations: @@ -613,8 +618,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. @@ -677,20 +682,20 @@ Instance methods: .. method:: date.toordinal() Return the proleptic Gregorian ordinal of the date, where January 1 of year 1 - has ordinal 1. For any :class:`date` object *d*, + has ordinal ``1``. For any :class:`date` object *d*, ``date.fromordinal(d.toordinal()) == d``. .. method:: date.weekday() - Return the day of the week as an integer, where Monday is 0 and Sunday is 6. + Return the day of the week as an integer, where Monday is ``0`` and Sunday is ``6``. For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also :meth:`isoweekday`. .. method:: date.isoweekday() - Return the day of the week as an integer, where Monday is 1 and Sunday is 7. + Return the day of the week as an integer, where Monday is ``1`` and Sunday is ``7``. For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also :meth:`weekday`, :meth:`isocalendar`. @@ -752,7 +757,7 @@ Instance methods: .. method:: date.strftime(format) Return a string representing the date, controlled by an explicit format string. - Format codes referring to hours, minutes or seconds will see 0 values. + Format codes referring to hours, minutes or seconds will see ``0`` values. See also :ref:`strftime-strptime-behavior` and :meth:`date.isoformat`. @@ -841,7 +846,7 @@ from a :class:`date` object and a :class:`.time` object. Like a :class:`date` object, :class:`.datetime` assumes the current Gregorian calendar extended in both directions; like a :class:`.time` object, -:class:`.datetime` assumes there are exactly 3600\*24 seconds in every day. +:class:`.datetime` assumes there are exactly ``3600 * 24`` seconds in every day. Constructor: @@ -945,7 +950,7 @@ Other constructors, all class methods: failure. .. versionchanged:: 3.6 - :meth:`fromtimestamp` may return instances with :attr:`.fold` set to 1. + :meth:`fromtimestamp` may return instances with :attr:`.fold` set to ``1``. .. classmethod:: datetime.utcfromtimestamp(timestamp) @@ -991,9 +996,9 @@ 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 - microsecond of the result are all 0, and :attr:`.tzinfo` is ``None``. + 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``. .. classmethod:: datetime.combine(date, time, tzinfo=time.tzinfo) @@ -1128,12 +1133,12 @@ Instance attributes (read-only): .. attribute:: datetime.month - Between 1 and 12 inclusive. + Between ``1`` and ``12`` inclusive. .. attribute:: datetime.day - Between 1 and the number of days in the given month of the given year. + Between ``1`` and the number of days in the given month of the given year. .. attribute:: datetime.hour @@ -1167,7 +1172,7 @@ 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 + The value ``0`` (1) represents the earlier (later) of the two moments with the same wall time representation. .. versionadded:: 3.6 @@ -1194,15 +1199,15 @@ 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 + 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. @@ -1216,7 +1221,7 @@ Supported operations: object *t* such that ``datetime2 + t == datetime1``. No time zone adjustments are done in this case. - If both are aware and have different :attr:`~.datetime.tzinfo` attributes, ``a-b`` acts + If both are aware and have different :attr:`~.datetime.tzinfo` attributes, ``a - b`` acts as if *a* and *b* were first converted to naive UTC datetimes. The result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())`` except that the implementation never overflows. @@ -1398,13 +1403,13 @@ Instance methods: .. method:: datetime.utctimetuple() If :class:`.datetime` instance *d* is naive, this is the same as - ``d.timetuple()`` except that :attr:`~.time.struct_time.tm_isdst` is forced to 0 regardless of what + ``d.timetuple()`` except that :attr:`~.time.struct_time.tm_isdst` is forced to ``0`` regardless of what ``d.dst()`` returns. DST is never in effect for a UTC time. 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 + normalized time is returned. :attr:`!tm_isdst` is forced to ``0``. Note + that an :exc:`OverflowError` may be raised if ``d.year`` was ``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year boundary. @@ -1462,13 +1467,13 @@ Instance methods: .. method:: datetime.weekday() - Return the day of the week as an integer, where Monday is 0 and Sunday is 6. + Return the day of the week as an integer, where Monday is ``0`` and Sunday is ``6``. The same as ``self.date().weekday()``. See also :meth:`isoweekday`. .. method:: datetime.isoweekday() - Return the day of the week as an integer, where Monday is 1 and Sunday is 7. + Return the day of the week as an integer, where Monday is ``1`` and Sunday is ``7``. The same as ``self.date().isoweekday()``. See also :meth:`weekday`, :meth:`isocalendar`. @@ -1483,15 +1488,15 @@ Instance methods: Return a string representing the date and time in ISO 8601 format: - - ``YYYY-MM-DDTHH:MM:SS.ffffff``, if :attr:`microsecond` is not 0 - - ``YYYY-MM-DDTHH:MM:SS``, if :attr:`microsecond` is 0 + - ``YYYY-MM-DDTHH:MM:SS.ffffff``, if :attr:`microsecond` is not ``0`` + - ``YYYY-MM-DDTHH:MM:SS``, if :attr:`microsecond` is ``0`` If :meth:`utcoffset` does not return ``None``, a string is appended, giving the UTC offset: - ``YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is not 0 - - ``YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is 0 + - ``YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is ``0`` Examples:: @@ -1519,7 +1524,7 @@ Instance methods: components of the time to include (the default is ``'auto'``). It can be one of the following: - - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is 0, + - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is ``0``, same as ``'microseconds'`` otherwise. - ``'hours'``: Include the :attr:`hour` in the two-digit ``HH`` format. - ``'minutes'``: Include :attr:`hour` and :attr:`minute` in ``HH:MM`` format. @@ -1735,7 +1740,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 ``None``. Class attributes: @@ -1790,7 +1795,7 @@ 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 + The value ``0`` (1) represents the earlier (later) of the two moments with the same wall time representation. .. versionadded:: 3.6 @@ -1885,16 +1890,16 @@ Instance methods: Return a string representing the time in ISO 8601 format, one of: - - ``HH:MM:SS.ffffff``, if :attr:`microsecond` is not 0 - - ``HH:MM:SS``, if :attr:`microsecond` is 0 + - ``HH:MM:SS.ffffff``, if :attr:`microsecond` is not ``0`` + - ``HH:MM:SS``, if :attr:`microsecond` is ``0`` - ``HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``, if :meth:`utcoffset` does not return ``None`` - - ``HH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is 0 and :meth:`utcoffset` does not return ``None`` + - ``HH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is ``0`` and :meth:`utcoffset` does not return ``None`` The optional argument *timespec* specifies the number of additional components of the time to include (the default is ``'auto'``). It can be one of the following: - - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is 0, + - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is ``0``, same as ``'microseconds'`` otherwise. - ``'hours'``: Include the :attr:`hour` in the two-digit ``HH`` format. - ``'minutes'``: Include :attr:`hour` and :attr:`minute` in ``HH:MM`` format. @@ -2083,7 +2088,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 +2125,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 @@ -2235,7 +2240,7 @@ to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous. :meth:`~.datetime.astimezone` mimics the local clock's behavior by mapping two adjacent UTC hours into the same local hour then. In the Eastern example, UTC times of the form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times -have the :attr:`~.datetime.fold` attribute set to 0 and the later times have it set to 1. +have the :attr:`~.datetime.fold` attribute set to ``0`` and the later times have it set to ``1``. For example, at the Fall back transition of 2016, we get:: >>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc) @@ -2411,8 +2416,8 @@ requires, and these work on all platforms with a standard C implementation. | | | Samstag (de_DE) | | +-----------+--------------------------------+------------------------+-------+ | ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | | -| | where 0 is Sunday and 6 is | | | -| | Saturday. | | | +| | where ``'0'`` is Sunday | | | +| | and ``'6'`` is Saturday. | | | +-----------+--------------------------------+------------------------+-------+ | ``%d`` | Day of the month as a | 01, 02, ..., 31 | \(9) | | | zero-padded decimal number. | | | @@ -2472,7 +2477,7 @@ requires, and these work on all platforms with a standard C implementation. | | decimal number. All days in a | | | | | new year preceding the first | | | | | Sunday are considered to be in | | | -| | week 0. | | | +| | week ``'0'``. | | | +-----------+--------------------------------+------------------------+-------+ | ``%W`` | Week number of the year | 00, 01, ..., 53 | \(7), | | | (Monday as the first day of | | \(9) | @@ -2480,7 +2485,7 @@ requires, and these work on all platforms with a standard C implementation. | | decimal number. All days in a | | | | | new year preceding the first | | | | | Monday are considered to be in | | | -| | week 0. | | | +| | week ``'0'``. | | | +-----------+--------------------------------+------------------------+-------+ | ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) | | | time representation. | 1988 (en_US); | | @@ -2509,7 +2514,7 @@ convenience. These parameters all correspond to ISO 8601 date values. | | the ISO week (``%V``). | | | +-----------+--------------------------------+------------------------+-------+ | ``%u`` | ISO 8601 weekday as a decimal | 1, 2, ..., 7 | | -| | number where 1 is Monday. | | | +| | number where ``'1'`` is Monday.| | | +-----------+--------------------------------+------------------------+-------+ | ``%V`` | ISO 8601 week as a decimal | 01, 02, ..., 53 | \(8), | | | number with Monday as | | \(9) | From b4d5661ef421950b55221a7b267ddf8176344bdb Mon Sep 17 00:00:00 2001 From: edson duarte Date: Fri, 19 Apr 2024 08:05:47 -0300 Subject: [PATCH 02/11] Updates based on PR review --- Doc/library/datetime.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index b30421048216bf..75e0721a26f266 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -114,7 +114,7 @@ Available Types :noindex: An idealized time, independent of any particular day, assuming that every day - has exactly ``24 * 60 * 60`` seconds. (There is no notion of "leap seconds" here.) + has exactly ``24*60*60`` seconds. (There is no notion of "leap seconds" here.) Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`, and :attr:`.tzinfo`. @@ -213,10 +213,10 @@ A :class:`timedelta` object represents a duration, the difference between two Only *days*, *seconds* and *microseconds* are stored internally. Arguments are converted to those units: - * A *millisecond* is converted to ``1000`` *microseconds*. - * A *minute* is converted to ``60`` *seconds*. - * An *hour* is converted to ``3600`` *seconds*. - * A *week* is converted to ``7`` *days*. + * A *millisecond* is converted to 1000 *microseconds*. + * A *minute* is converted to 60 *seconds*. + * An *hour* is converted to 3600 *seconds*. + * A *week* is converted to 7 *days*. and days, seconds and microseconds are then normalized so that the representation is unique, with @@ -1740,7 +1740,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 ``None``. + default to ``0`` except *tzinfo*, which defaults to :const:`None`. Class attributes: From 88409213ce17f9e37a077a011ffe3adc16e79b68 Mon Sep 17 00:00:00 2001 From: edson duarte Date: Mon, 22 Apr 2024 20:15:18 -0300 Subject: [PATCH 03/11] Revert some changes to focus only on backquotes --- Doc/library/datetime.rst | 36 +++++++++++++++--------------------- 1 file changed, 15 insertions(+), 21 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 75e0721a26f266..5a13ad4f6192ce 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -213,10 +213,10 @@ A :class:`timedelta` object represents a duration, the difference between two Only *days*, *seconds* and *microseconds* are stored internally. Arguments are converted to those units: - * A *millisecond* is converted to 1000 *microseconds*. - * A *minute* is converted to 60 *seconds*. - * An *hour* is converted to 3600 *seconds*. - * A *week* is converted to 7 *days*. + * A millisecond is converted to 1000 microseconds. + * A minute is converted to 60 seconds. + * An hour is converted to 3600 seconds. + * A week is converted to 7 days. and days, seconds and microseconds are then normalized so that the representation is unique, with @@ -285,21 +285,15 @@ Note that, because of normalization, ``timedelta.max > -timedelta.min`` is true. Instance attributes (read-only): - -.. attribute:: timedelta.days - - Between ``-999999999`` and ``999999999`` inclusive. - - -.. attribute:: timedelta.seconds - - Between ``0`` and ``86399`` inclusive. - - -.. attribute:: timedelta.microseconds - - Between ``0`` and ``999999`` inclusive. - ++------------------+--------------------------------------------+ +| Attribute | Value | ++==================+============================================+ +| ``days`` | Between -999999999 and 999999999 inclusive | ++------------------+--------------------------------------------+ +| ``seconds`` | Between 0 and 86399 inclusive | ++------------------+--------------------------------------------+ +| ``microseconds`` | Between 0 and 999999 inclusive | ++------------------+--------------------------------------------+ Supported operations: @@ -375,7 +369,7 @@ 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. @@ -1221,7 +1215,7 @@ Supported operations: object *t* such that ``datetime2 + t == datetime1``. No time zone adjustments are done in this case. - If both are aware and have different :attr:`~.datetime.tzinfo` attributes, ``a - b`` acts + If both are aware and have different :attr:`~.datetime.tzinfo` attributes, ``a-b`` acts as if *a* and *b* were first converted to naive UTC datetimes. The result is ``(a.replace(tzinfo=None) - a.utcoffset()) - (b.replace(tzinfo=None) - b.utcoffset())`` except that the implementation never overflows. From ed6d923702c1845f1b0ff6982cc7d6b6b9b0ede0 Mon Sep 17 00:00:00 2001 From: edson duarte Date: Tue, 23 Apr 2024 12:32:18 -0300 Subject: [PATCH 04/11] More updates based on PR review --- Doc/library/datetime.rst | 38 +++++++++++++++++++------------------- 1 file changed, 19 insertions(+), 19 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 5a13ad4f6192ce..d723acdab3935a 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -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`` is true. +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,11 +302,11 @@ 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. | @@ -320,8 +320,8 @@ Supported operations: | | 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| @@ -347,8 +347,8 @@ Supported operations: | | -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 | @@ -502,7 +502,7 @@ Other constructors, all class methods: .. classmethod:: date.fromordinal(ordinal) Return the date corresponding to the proleptic Gregorian ordinal, where - January 1 of year 1 has ordinal ``1``. + January 1 of year 1 has ordinal 1. :exc:`ValueError` is raised unless ``1 <= ordinal <= date.max.toordinal()``. For any date *d*, @@ -582,10 +582,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) | @@ -990,7 +990,7 @@ 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 + 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``. @@ -2410,8 +2410,8 @@ requires, and these work on all platforms with a standard C implementation. | | | Samstag (de_DE) | | +-----------+--------------------------------+------------------------+-------+ | ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | | -| | where ``'0'`` is Sunday | | | -| | and ``'6'`` is Saturday. | | | +| | where 0 is Sunday | | | +| | and 6 is Saturday. | | | +-----------+--------------------------------+------------------------+-------+ | ``%d`` | Day of the month as a | 01, 02, ..., 31 | \(9) | | | zero-padded decimal number. | | | @@ -2471,7 +2471,7 @@ requires, and these work on all platforms with a standard C implementation. | | decimal number. All days in a | | | | | new year preceding the first | | | | | Sunday are considered to be in | | | -| | week ``'0'``. | | | +| | week 0. | | | +-----------+--------------------------------+------------------------+-------+ | ``%W`` | Week number of the year | 00, 01, ..., 53 | \(7), | | | (Monday as the first day of | | \(9) | @@ -2479,7 +2479,7 @@ requires, and these work on all platforms with a standard C implementation. | | decimal number. All days in a | | | | | new year preceding the first | | | | | Monday are considered to be in | | | -| | week ``'0'``. | | | +| | week 0. | | | +-----------+--------------------------------+------------------------+-------+ | ``%c`` | Locale's appropriate date and || Tue Aug 16 21:30:00 | \(1) | | | time representation. | 1988 (en_US); | | @@ -2508,7 +2508,7 @@ convenience. These parameters all correspond to ISO 8601 date values. | | the ISO week (``%V``). | | | +-----------+--------------------------------+------------------------+-------+ | ``%u`` | ISO 8601 weekday as a decimal | 1, 2, ..., 7 | | -| | number where ``'1'`` is Monday.| | | +| | number where 1 is Monday. | | | +-----------+--------------------------------+------------------------+-------+ | ``%V`` | ISO 8601 week as a decimal | 01, 02, ..., 53 | \(8), | | | number with Monday as | | \(9) | From 7d98dac0d43565bc4bae7dab3efb043ff480fa0e Mon Sep 17 00:00:00 2001 From: edson duarte Date: Tue, 23 Apr 2024 15:01:41 -0300 Subject: [PATCH 05/11] Updates based on PR review --- Doc/library/datetime.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index d723acdab3935a..c9cfbd6cebb63d 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -347,7 +347,7 @@ Supported operations: | | -t1.seconds*, -t1.microseconds)``, | | | 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) | +--------------------------------+-----------------------------------------------+ | ``str(t)`` | Returns a string in the form | @@ -1201,7 +1201,7 @@ Supported operations: 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. @@ -2410,8 +2410,8 @@ requires, and these work on all platforms with a standard C implementation. | | | Samstag (de_DE) | | +-----------+--------------------------------+------------------------+-------+ | ``%w`` | Weekday as a decimal number, | 0, 1, ..., 6 | | -| | where 0 is Sunday | | | -| | and 6 is Saturday. | | | +| | where 0 is Sunday and 6 is | | | +| | Saturday. | | | +-----------+--------------------------------+------------------------+-------+ | ``%d`` | Day of the month as a | 01, 02, ..., 31 | \(9) | | | zero-padded decimal number. | | | From 4924fd0ccc76a8c82742512062c1f3434bcc47c1 Mon Sep 17 00:00:00 2001 From: edson duarte Date: Wed, 24 Apr 2024 08:17:39 -0300 Subject: [PATCH 06/11] Updates based on PR review --- Doc/library/datetime.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index c9cfbd6cebb63d..dec0cb96b8c590 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -569,12 +569,12 @@ Instance attributes (read-only): .. attribute:: date.month - Between ``1`` and ``12`` inclusive. + Between 1 and 12 inclusive. .. attribute:: date.day - Between ``1`` and the number of days in the given month of the given year. + Between 1 and the number of days in the given month of the given year. Supported operations: @@ -676,20 +676,20 @@ Instance methods: .. method:: date.toordinal() Return the proleptic Gregorian ordinal of the date, where January 1 of year 1 - has ordinal ``1``. For any :class:`date` object *d*, + has ordinal 1. For any :class:`date` object *d*, ``date.fromordinal(d.toordinal()) == d``. .. method:: date.weekday() - Return the day of the week as an integer, where Monday is ``0`` and Sunday is ``6``. + Return the day of the week as an integer, where Monday is 0 and Sunday is 6. For example, ``date(2002, 12, 4).weekday() == 2``, a Wednesday. See also :meth:`isoweekday`. .. method:: date.isoweekday() - Return the day of the week as an integer, where Monday is ``1`` and Sunday is ``7``. + Return the day of the week as an integer, where Monday is 1 and Sunday is 7. For example, ``date(2002, 12, 4).isoweekday() == 3``, a Wednesday. See also :meth:`weekday`, :meth:`isocalendar`. @@ -840,7 +840,7 @@ from a :class:`date` object and a :class:`.time` object. Like a :class:`date` object, :class:`.datetime` assumes the current Gregorian calendar extended in both directions; like a :class:`.time` object, -:class:`.datetime` assumes there are exactly ``3600 * 24`` seconds in every day. +:class:`.datetime` assumes there are exactly ``3600*24`` seconds in every day. Constructor: @@ -1127,12 +1127,12 @@ Instance attributes (read-only): .. attribute:: datetime.month - Between ``1`` and ``12`` inclusive. + Between 1 and 12 inclusive. .. attribute:: datetime.day - Between ``1`` and the number of days in the given month of the given year. + Between 1 and the number of days in the given month of the given year. .. attribute:: datetime.hour @@ -1166,7 +1166,7 @@ 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 + The value ``0`` (``1``) represents the earlier (later) of the two moments with the same wall time representation. .. versionadded:: 3.6 @@ -1192,7 +1192,7 @@ Supported operations: +---------------------------------------+--------------------------------+ (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 result has the same :attr:`~.datetime.tzinfo` attribute as the input datetime, and ``datetime2 - datetime1 == timedelta`` after. :exc:`OverflowError` is raised if @@ -1461,13 +1461,13 @@ Instance methods: .. method:: datetime.weekday() - Return the day of the week as an integer, where Monday is ``0`` and Sunday is ``6``. + Return the day of the week as an integer, where Monday is 0 and Sunday is 6. The same as ``self.date().weekday()``. See also :meth:`isoweekday`. .. method:: datetime.isoweekday() - Return the day of the week as an integer, where Monday is ``1`` and Sunday is ``7``. + Return the day of the week as an integer, where Monday is 1 and Sunday is 7. The same as ``self.date().isoweekday()``. See also :meth:`weekday`, :meth:`isocalendar`. @@ -1489,7 +1489,7 @@ Instance methods: appended, giving the UTC offset: - ``YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` - is not 0 + is not ``0`` - ``YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is ``0`` Examples:: From 864f18b70cbecb3f6e50695f60588fe60a93d963 Mon Sep 17 00:00:00 2001 From: edson duarte Date: Wed, 24 Apr 2024 10:22:05 -0300 Subject: [PATCH 07/11] Updates based on PR review --- Doc/library/datetime.rst | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index dec0cb96b8c590..5592f1378adfac 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -302,8 +302,9 @@ 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 | @@ -1166,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 From ce117ad3264e9ac635b27178793369cd9f66c611 Mon Sep 17 00:00:00 2001 From: edson duarte Date: Wed, 24 Apr 2024 10:38:35 -0300 Subject: [PATCH 08/11] Update based on PR review --- Doc/library/datetime.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 5592f1378adfac..dd7e34395793f2 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -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 From 17947e2358ee550033c98e51af95548c423c7075 Mon Sep 17 00:00:00 2001 From: edson duarte Date: Wed, 24 Apr 2024 11:45:34 -0300 Subject: [PATCH 09/11] Remove code formatting for 0 and 1 --- Doc/library/datetime.rst | 56 ++++++++++++++++++++-------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index dd7e34395793f2..2d841847c6d831 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -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. @@ -614,7 +614,7 @@ Notes: (3) 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) :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() @@ -752,7 +752,7 @@ Instance methods: .. method:: date.strftime(format) Return a string representing the date, controlled by an explicit format string. - Format codes referring to hours, minutes or seconds will see ``0`` values. + Format codes referring to hours, minutes or seconds will see 0 values. See also :ref:`strftime-strptime-behavior` and :meth:`date.isoformat`. @@ -841,7 +841,7 @@ from a :class:`date` object and a :class:`.time` object. Like a :class:`date` object, :class:`.datetime` assumes the current Gregorian calendar extended in both directions; like a :class:`.time` object, -:class:`.datetime` assumes there are exactly ``3600*24`` seconds in every day. +:class:`.datetime` assumes there are exactly 3600\*24 seconds in every day. Constructor: @@ -945,7 +945,7 @@ Other constructors, all class methods: failure. .. versionchanged:: 3.6 - :meth:`fromtimestamp` may return instances with :attr:`.fold` set to ``1``. + :meth:`fromtimestamp` may return instances with :attr:`.fold` set to 1. .. classmethod:: datetime.utcfromtimestamp(timestamp) @@ -993,7 +993,7 @@ Other constructors, all class methods: 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 - microsecond of the result are all ``0``, and :attr:`.tzinfo` is ``None``. + microsecond of the result are all 0, and :attr:`.tzinfo` is ``None``. .. classmethod:: datetime.combine(date, time, tzinfo=time.tzinfo) @@ -1167,7 +1167,7 @@ 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 values ``0`` and ``1`` represent, respectively, the earlier and later of the two + The values 0 and 1 represent, respectively, the earlier and later of the two moments with the same wall time representation. .. versionadded:: 3.6 @@ -1387,23 +1387,23 @@ 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() If :class:`.datetime` instance *d* is naive, this is the same as - ``d.timetuple()`` except that :attr:`~.time.struct_time.tm_isdst` is forced to ``0`` regardless of what + ``d.timetuple()`` except that :attr:`~.time.struct_time.tm_isdst` is forced to 0 regardless of what ``d.dst()`` returns. DST is never in effect for a UTC time. 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 + normalized time is returned. :attr:`!tm_isdst` is forced to 0. Note that an :exc:`OverflowError` may be raised if ``d.year`` was ``MINYEAR`` or ``MAXYEAR`` and UTC adjustment spills over a year boundary. @@ -1483,15 +1483,15 @@ Instance methods: Return a string representing the date and time in ISO 8601 format: - - ``YYYY-MM-DDTHH:MM:SS.ffffff``, if :attr:`microsecond` is not ``0`` - - ``YYYY-MM-DDTHH:MM:SS``, if :attr:`microsecond` is ``0`` + - ``YYYY-MM-DDTHH:MM:SS.ffffff``, if :attr:`microsecond` is not 0 + - ``YYYY-MM-DDTHH:MM:SS``, if :attr:`microsecond` is 0 If :meth:`utcoffset` does not return ``None``, a string is appended, giving the UTC offset: - ``YYYY-MM-DDTHH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` - is not ``0`` - - ``YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is ``0`` + is not 0 + - ``YYYY-MM-DDTHH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is 0 Examples:: @@ -1519,7 +1519,7 @@ Instance methods: components of the time to include (the default is ``'auto'``). It can be one of the following: - - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is ``0``, + - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is 0, same as ``'microseconds'`` otherwise. - ``'hours'``: Include the :attr:`hour` in the two-digit ``HH`` format. - ``'minutes'``: Include :attr:`hour` and :attr:`minute` in ``HH:MM`` format. @@ -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,7 +1790,7 @@ 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 values ``0`` and ``1`` represent, respectively, the earlier and later of the two + The values 0 and 1 represent, respectively, the earlier and later of the two moments with the same wall time representation. .. versionadded:: 3.6 @@ -1885,16 +1885,16 @@ Instance methods: Return a string representing the time in ISO 8601 format, one of: - - ``HH:MM:SS.ffffff``, if :attr:`microsecond` is not ``0`` - - ``HH:MM:SS``, if :attr:`microsecond` is ``0`` + - ``HH:MM:SS.ffffff``, if :attr:`microsecond` is not 0 + - ``HH:MM:SS``, if :attr:`microsecond` is 0 - ``HH:MM:SS.ffffff+HH:MM[:SS[.ffffff]]``, if :meth:`utcoffset` does not return ``None`` - - ``HH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is ``0`` and :meth:`utcoffset` does not return ``None`` + - ``HH:MM:SS+HH:MM[:SS[.ffffff]]``, if :attr:`microsecond` is 0 and :meth:`utcoffset` does not return ``None`` The optional argument *timespec* specifies the number of additional components of the time to include (the default is ``'auto'``). It can be one of the following: - - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is ``0``, + - ``'auto'``: Same as ``'seconds'`` if :attr:`microsecond` is 0, same as ``'microseconds'`` otherwise. - ``'hours'``: Include the :attr:`hour` in the two-digit ``HH`` format. - ``'minutes'``: Include :attr:`hour` and :attr:`minute` in ``HH:MM`` format. @@ -2235,7 +2235,7 @@ to 1:00 (standard time) again. Local times of the form 1:MM are ambiguous. :meth:`~.datetime.astimezone` mimics the local clock's behavior by mapping two adjacent UTC hours into the same local hour then. In the Eastern example, UTC times of the form 5:MM and 6:MM both map to 1:MM when converted to Eastern, but earlier times -have the :attr:`~.datetime.fold` attribute set to ``0`` and the later times have it set to ``1``. +have the :attr:`~.datetime.fold` attribute set to 0 and the later times have it set to 1. For example, at the Fall back transition of 2016, we get:: >>> u0 = datetime(2016, 11, 6, 4, tzinfo=timezone.utc) @@ -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 From 8b8cd5aa6530bf81dfa977077ded7a5abf2dbf2e Mon Sep 17 00:00:00 2001 From: edson duarte Date: Wed, 24 Apr 2024 12:36:34 -0300 Subject: [PATCH 10/11] Updates based on PR review --- Doc/library/datetime.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index 2d841847c6d831..f507f3e4491997 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -344,11 +344,11 @@ Supported operations: | ``+t1`` | Returns a :class:`timedelta` object with the | | | same value. (2) | +--------------------------------+-----------------------------------------------+ -| ``-t1`` | equivalent to ``timedelta(-t1.days, | +| ``-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``, | +| ``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 | @@ -1193,7 +1193,7 @@ Supported operations: +---------------------------------------+--------------------------------+ (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 result has the same :attr:`~.datetime.tzinfo` attribute as the input datetime, and ``datetime2 - datetime1 == timedelta`` after. :exc:`OverflowError` is raised if From 5731e3d1d8e0443177bbd952039ca8ab5fa3af88 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 24 Apr 2024 21:37:41 +0200 Subject: [PATCH 11/11] Update Doc/library/datetime.rst --- Doc/library/datetime.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst index f507f3e4491997..84fede472eeacc 100644 --- a/Doc/library/datetime.rst +++ b/Doc/library/datetime.rst @@ -114,7 +114,7 @@ Available Types :noindex: An idealized time, independent of any particular day, assuming that every day - has exactly ``24*60*60`` seconds. (There is no notion of "leap seconds" here.) + has exactly 24\*60\*60 seconds. (There is no notion of "leap seconds" here.) Attributes: :attr:`hour`, :attr:`minute`, :attr:`second`, :attr:`microsecond`, and :attr:`.tzinfo`.