Skip to content
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.

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

Improve documentation about converting datetime.timedelta to scalars #80319

Open
pganssle opened this issue Feb 27, 2019 · 5 comments
Open

Improve documentation about converting datetime.timedelta to scalars #80319

pganssle opened this issue Feb 27, 2019 · 5 comments
Labels
3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir stdlib Python modules in the Lib dir

Comments

@pganssle
Copy link
Member

BPO 36138
Nosy @freddrake, @ncoghlan, @abalkin, @pganssle, @miss-islington, @0xYasser
PRs
  • bpo-36138: Improve docs about converting datetime.timedelta to scalars. #12137
  • [3.7] bpo-36138: Clarify docs about converting datetime.timedelta to scalars. (GH-12137) #12362
  • Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.

    Show more details

    GitHub fields:

    assignee = None
    closed_at = None
    created_at = <Date 2019-02-27.14:54:37.765>
    labels = ['3.8', '3.7', 'library', 'docs']
    title = 'Improve documentation about converting datetime.timedelta to scalars'
    updated_at = <Date 2019-03-16.05:34:12.160>
    user = 'https://github.com/pganssle'

    bugs.python.org fields:

    activity = <Date 2019-03-16.05:34:12.160>
    actor = 'ncoghlan'
    assignee = 'docs@python'
    closed = False
    closed_date = None
    closer = None
    components = ['Documentation', 'Library (Lib)']
    creation = <Date 2019-02-27.14:54:37.765>
    creator = 'p-ganssle'
    dependencies = []
    files = []
    hgrepos = []
    issue_num = 36138
    keywords = ['patch']
    message_count = 5.0
    messages = ['336765', '336980', '338052', '338053', '338054']
    nosy_count = 7.0
    nosy_names = ['fdrake', 'ncoghlan', 'belopolsky', 'docs@python', 'p-ganssle', 'miss-islington', 'Yasser Alshalaan']
    pr_nums = ['12137', '12362']
    priority = 'normal'
    resolution = None
    stage = 'patch review'
    status = 'open'
    superseder = None
    type = None
    url = 'https://bugs.python.org/issue36138'
    versions = ['Python 3.7', 'Python 3.8']

    @pganssle
    Copy link
    Member Author

    In a recent python-dev thread, there was some confusion about how to get something like timedelta.total_microseconds(). There is already an existing, supported idiom for this, which is that timedelta implements division:

        td = timedelta(hours=1)
        num_microseconds = td / timedelta(microseconds=1)

    In this e-mail ( https://mail.python.org/pipermail/python-dev/2019-February/156351.html ), Nick Coghlan proposed that we update the documentation and there were no objections, quoting:

    * In the "Supported Operations" section of https://docs.python.org/3/library/datetime.html#timedelta-objects,
      change "Division (3) of t2 by t3." to "Division (3) of overall
      duration t2 by interval unit t3."
    * In the total_seconds() documentation, add a sentence "For interval units
      other than seconds, use the division form directly (e.g. `td / timedelta(microseconds=1)`)"
    

    I am starting this issue to track that change.

    @pganssle pganssle added 3.7 (EOL) end of life 3.8 only security fixes labels Feb 27, 2019
    @pganssle pganssle added docs Documentation in the Doc dir stdlib Python modules in the Lib dir labels Feb 27, 2019
    @0xYasser
    Copy link
    Mannequin

    0xYasser mannequin commented Mar 2, 2019

    I'll do this in a moment I'll have the PR

    @ncoghlan
    Copy link
    Contributor

    New changeset f40b4a0 by Nick Coghlan (Yasser A) in branch 'master':
    bpo-36138: Clarify docs about converting datetime.timedelta to scalars. (GH-12137)
    f40b4a0

    @miss-islington
    Copy link
    Contributor

    New changeset e213cd6 by Miss Islington (bot) in branch '3.7':
    bpo-36138: Clarify docs about converting datetime.timedelta to scalars. (GH-12137)
    e213cd6

    @ncoghlan
    Copy link
    Contributor

    I've merged Yasser's PR (thank you!), but in the review discussion for that, we noticed something else: the total_seconds() documentation mentions the floating point dynamic resolution problem, but doesn't mention using // or divmod() as the fix for that, while the operator table doesn't mention the dynamic resolution problem at all.

    So I haven't closed the issue yet, as fixing that feel in-scope for this issue, even though I didn't want to hold up the initial PR for it.

    @ezio-melotti ezio-melotti transferred this issue from another repository Apr 10, 2022
    Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
    Labels
    3.7 (EOL) end of life 3.8 only security fixes docs Documentation in the Doc dir stdlib Python modules in the Lib dir
    Projects
    Development

    No branches or pull requests

    3 participants