gh-132642: document how to render human-readable `timedelta` objects (GH-133825)
(cherry picked from commit efcc42ba70)
Co-authored-by: Kentaro Jay Takahashi <64148935+KentaroJay@users.noreply.github.com>
* Clarify datetime `replace` documentation
In #115684, HopedForLuck noted that `datetime.date.replace()`
documentation was confusing because it looked like it would be changing
immutable objects.
This documentation change specifies that the `replace()` methods in
`datetime` return new objects. This uses similar wording to the
documentation for `datetime.combine()`, which specifies that a new
datetime is returned. This is also similar to wording for
`string.replace()`, except `string.replace()` emphasizes that a "copy"
is returned.
Resolves#115684.
* Include reviewer comments
Thanks Privat33r-dev for the comments!
---------
Co-authored-by: Paul Ganssle <1377457+pganssle@users.noreply.github.com>
Now the special comparison methods like `__eq__` and `__lt__` return
NotImplemented if one of comparands is date and other is datetime
instead of ignoring the time part and the time zone or forcefully
return "not equal" or raise TypeError.
It makes comparison of date and datetime subclasses more symmetric
and allows to change the default behavior by overriding
the special comparison methods in subclasses.
It is now the same as if date and datetime was independent classes.
It creates a modified copy of an object by calling the object's
__replace__() method.
It is a generalization of dataclasses.replace(), named tuple's _replace()
method and replace() methods in various classes, and supports all these
stdlib classes.
Using `datetime.datetime.utcnow()` and `datetime.datetime.utcfromtimestamp()` will now raise a `DeprecationWarning`.
We also have removed our internal uses of these functions and documented the change.
This removes a section of the `strftime` and `strptime` documentation that refers to a bygone era when `strftime` would return an encoded byte string.
---------
Co-authored-by: Paul Ganssle <1377457+pganssle@users.noreply.github.com>
The new wording better reflects the cases where `datetime.strptime` differs from` time.strptime`.
---------
Co-authored-by: Paul Ganssle <git@m.ganssle.io>
The default `tzinfo` param of the `combine()` signature pseudocode was erroneously `self.tzinfo`.
`self` has no meaning in the context of a classmethod, and the datetime class itself has no `tzinfo` attribute. The correct default pseudocode is `time.tzinfo`, reflecting that the default is the `tzinfo` attribute of the `time` parameter.
datetime.isoformat generates the tzoffset with colons, but there
was no format code to make strftime output the same format.
for simplicity and consistency the %:z formatting behaves mostly
as %z, with the exception of adding colons. this includes the
dynamic behaviour of adding seconds and microseconds only when
needed (when not 0).
this fixes the still open "generate" part of this issue:
https://github.com/python/cpython/issues/69142
Co-authored-by: Kumar Aditya <59607654+kumaraditya303@users.noreply.github.com>
* Restore default role check in `make check`.
* Options first, then files.
* Update `make.bat` too.
* Add a comment explaining the extra options.
* No reason to ignore the README.rst.
* Enable default-role check in sphinx-lint.
Co-authored-by: Julien Palard <julien@palard.fr>
* Update sphinx-lint default-role check.
* Fix use of the default role in the docs.
* Update make.bat to check for the default role too.
* Fix comment in make.bat.
Co-authored-by: Julien Palard <julien@palard.fr>
