8000 gh-132642: Add documentation on how to render human-readable timedelta object by KentaroJay · Pull Request #133825 · python/cpython · GitHub
[go: up one dir, main page]
Skip to content

gh-132642: Add documentation on how to render human-readable timedelta object #133825

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 15 commits into from
May 10, 2025
Merged

gh-132642: Add documentation on how to render human-readable timedelta object #133825

merged 15 commits into from
May 10, 2025

Conversation

KentaroJay
Copy link
Contributor
@KentaroJay KentaroJay commented May 10, 2025 •
edited
Loading

@python-cla-bot
Copy link
python-cla-bot bot commented May 10, 2025 •
edited
Loading

All commit authors signed the Contributor License Agreement.

CLA signed

@bedevere-app bedevere-app bot added docs Documentation in the Doc dir skip news labels May 10, 2025
@bedevere-app bedevere-app bot mentioned this pull request May 10, 2025
Closed
@github-project-automation github-project-automation bot moved this to Todo in Docs PRs May 10, 2025
StanFromIreland
StanFromIreland reviewed May 10, 2025
View reviewed changes
picnixz
picnixz reviewed May 10, 2025
View reviewed changes
KentaroJay and others added 2 commits May 10, 2025 13:35
@KentaroJay
Fix
b4cb1cd
@KentaroJay @picnixz
Update Doc/library/datetime.rst
2a69fe6 
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
picnixz
picnixz reviewed May 10, 2025
View reviewed changes
KentaroJay and others added 4 commits May 10, 2025 13:42
@KentaroJay
Fix
0594cd5
@KentaroJay @picnixz
Fix
bddce2d 
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
@KentaroJay
Fix
a3ca8f0
@KentaroJay
Merge branch 'main' into fix-issue-132642
278f291
StanFromIreland
StanFromIreland reviewed May 10, 2025
View reviewed changes
@KentaroJay
Copy link
Contributor Author
KentaroJay commented May 10, 2025 •
edited
Loading

I just confirmed the code on the doc is working as expected with the local Python(3.11.11).

$ python
Python 3.11.11 (main, Mar 29 2025, 18:04:05) [Clang 16.0.0 (clang-1600.0.26.6)] on darwin
Type "help", "copyright", "credits" or "license" for more information.
>>> from datetime import timedelta
>>> d = timedelta(hours=-1)
>>> str(d)
'-1 day, 23:00:00'
>>> def pretty_timedelta(td):
...     if td.days >= 0:
...             return str(td)
...     return f'-({-td!s})'
...
>>> pretty_timedelta(d)
'-(1:00:00)'

@KentaroJay @StanFromIreland
Update Doc/library/datetime.rst
90815d7 
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
@StanFromIreland
Copy link
Contributor

I just confirmed the code on the doc is working as expected with the local Python(3.11.11).

We could make this a doctest? Anything against this @picnixz ?

@picnixz
Copy link
Member
picnixz commented May 10, 2025 •
edited
Loading

We don't need more doctests IMO. The doctest job is already slow IMO. We didn't do doctests for the other code blocks. It's better to test that str(d) == ... and f'-({-td!s}' == ... in Lib/test directly.

8000
StanFromIreland
StanFromIreland approved these changes May 10, 2025
View reviewed changes
Copy link
Contributor
@StanFromIreland StanFromIreland left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM (with one minor change)

@KentaroJay @StanFromIreland
Update Doc/library/datetime.rst
d5dea14 
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
picnixz
picnixz reviewed May 10, 2025
View reviewed changes
8000
@KentaroJay @picnixz
Update Doc/library/datetime.rst
118ef87 
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
@KentaroJay
Copy link
Contributor Author
KentaroJay commented May 10, 2025 •
edited
Loading

We don't need more doctests IMO. The doctest job is already slow IMO. We didn't do doctests for the other code blocks. It's better to test that str(d) == ... and f'-({-td!s}' == ... in Lib/test directly.

@picnixz
Regarding this discussion, I plan to add the following test:

eq(f'-({-td(hours=-1)!s})', "-(1:00:00)")

at:

cpython/Lib/test/datetimetester.py

Lines 755 to 774 in dbca27c

def test_str(self):
td = timedelta
eq = self.assertEqual
eq(str(td(1)), "1 day, 0:00:00")
eq(str(td(-1)), "-1 day, 0:00:00")
eq(str(td(2)), "2 days, 0:00:00")
eq(str(td(-2)), "-2 days, 0:00:00")
eq(str(td(hours=12, minutes=58, seconds=59)), "12:58:59")
eq(str(td(hours=2, minutes=3, seconds=4)), "2:03:04")
eq(str(td(weeks=-30, hours=23, minutes=12, seconds=34)),
"-210 days, 23:12:34")
eq(str(td(milliseconds=1)), "0:00:00.001000")
eq(str(td(microseconds=3)), "0:00:00.000003")
eq(str(td(days=999999999, hours=23, minutes=59, seconds=59,
microseconds=999999)),
"999999999 days, 23:59:59.999999")

Does that make sense?

@picnixz
Copy link
Member
picnixz commented May 10, 2025

Regarding this discussion, I plan to add the following test here at:

You can add it and add a note saying that it's for the docs recipe.

@KentaroJay KentaroJay requested a review from picnixz May 10, 2025 13:35
picnixz
picnixz reviewed May 10, 2025
View reviewed changes
@KentaroJay @picnixz
Update datetimetester.py
f67ec7e 
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
@picnixz picnixz self-assigned this May 10, 2025
@picnixz picnixz merged commit efcc42b into python:main May 10, 2025
43 checks passed
@github-project-automation github-project-automation bot moved this from Todo to Done in Docs PRs May 10, 2025
@picnixz picnixz added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels May 10, 2025
@miss-islington-app
Copy link

Thanks @KentaroJay for the PR, and @picnixz for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

@miss-islington-app
Copy link

Thanks @KentaroJay for the PR, and @picnixz for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖 I'm not a witch! I'm not a witch!

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 10, 2025
@KentaroJay @miss-islington
pythongh-132642: document how to render human-readable timedelta ob…
a08f4df 
…jects (pythonGH-133825)

(cherry picked from commit efcc42b)

Co-authored-by: Kentaro Jay Takahashi <64148935+KentaroJay@users.noreply.github.com>
@bedevere-app
Copy link
bedevere-app bot commented May 10, 2025

GH-133836 is a backport of this pull request to the 3.13 branch.

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 10, 2025
@KentaroJay @miss-islington
pythongh-132642: document how to render human-readable timedelta ob…
49f52f4 
…jects (pythonGH-133825)

(cherry picked from commit efcc42b)

Co-authored-by: Kentaro Jay Takahashi <64148935+KentaroJay@users.noreply.github.com>
@bedevere-app bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label May 10, 2025
@bedevere-app
Copy link
bedevere-app bot commented May 10, 2025

GH-133837 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label May 10, 2025
picnixz pushed a commit that referenced this pull request May 10, 2025
@miss-islington @KentaroJay
[3.13] gh-132642: document how to render human-readable timedelta o…
18501a1 
…bjects (GH-133825) (#133836)

gh-132642: document how to render human-readable `timedelta` objects (GH-133825)
(cherry picked from commit efcc42b)

Co-authored-by: Kentaro Jay Takahashi <64148935+KentaroJay@users.noreply.github.com>
picnixz pushed a commit that referenced this pull request May 10, 2025
@miss-islington @KentaroJay
[3.14] gh-132642: document how to render human-readable timedelta o…
13c94d0 
…bjects (GH-133825) (#133837)

gh-132642: document how to render human-readable `timedelta` objects (GH-133825)
(cherry picked from commit efcc42b)

Co-authored-by: Kentaro Jay Takahashi <64148935+KentaroJay@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@picnixz picnixz picnixz approved these changes

@StanFromIreland StanFromIreland StanFromIreland approved these changes

@pganssle pganssle Awaiting requested review from pganssle pganssle is a code owner

@abalkin abalkin Awaiting requested review from abalkin abalkin is a code owner

Assignees

@picnixz picnixz

Labels
docs Documentation in the Doc dir skip news
Projects
Docs PRs
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
3 participants
@KentaroJay @StanFromIreland @picnixz
0