Improve documentation about converting datetime.timedelta to scalars

[pganssle]

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]

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.

[0xYasser]

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

[ncoghlan]

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]

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]

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.