From f40b4a0b6277b2779b9ded3736325489f2af93e4 Mon Sep 17 00:00:00 2001
From: Yasser A <yalshalaan@gmail.com>
Date: Fri, 15 Mar 2019 23:56:58 -0400
Subject: [PATCH] bpo-36138: Clarify docs about converting datetime.timedelta
 to scalars. (GH-12137)

Be explicit that timedelta division converts an overall duration to the interval
units given by the denominator.
---
 Doc/library/datetime.rst                                  | 8 +++++---
 .../2019-03-02-00-40-57.bpo-36138.yfjNzG.rst              | 1 +
 2 files changed, 6 insertions(+), 3 deletions(-)
 create mode 100644 Misc/NEWS.d/next/Documentation/2019-03-02-00-40-57.bpo-36138.yfjNzG.rst

diff --git a/Doc/library/datetime.rst b/Doc/library/datetime.rst
index 121f73bbe85..1ee23c2175a 100644
--- a/Doc/library/datetime.rst
+++ b/Doc/library/datetime.rst
@@ -254,8 +254,9 @@ Supported operations:
 |                                | rounded to the nearest multiple of            |
 |                                | timedelta.resolution using round-half-to-even.|
 +--------------------------------+-----------------------------------------------+
-| ``f = t2 / t3``                | Division (3) of *t2* by *t3*.  Returns a      |
-|                                | :class:`float` object.                        |
+| ``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|
 |                                | is rounded to the nearest multiple of         |
@@ -351,7 +352,8 @@ Instance methods:
 .. method:: timedelta.total_seconds()
 
    Return the total number of seconds contained in the duration. Equivalent to
-   ``td / timedelta(seconds=1)``.
+   ``td / timedelta(seconds=1)``. For interval units other than seconds, use the
+   division form directly (e.g. ``td / timedelta(microseconds=1)``).
 
    Note that for very large time intervals (greater than 270 years on
    most platforms) this method will lose microsecond accuracy.
diff --git a/Misc/NEWS.d/next/Documentation/2019-03-02-00-40-57.bpo-36138.yfjNzG.rst b/Misc/NEWS.d/next/Documentation/2019-03-02-00-40-57.bpo-36138.yfjNzG.rst
new file mode 100644
index 00000000000..f5352bb3958
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2019-03-02-00-40-57.bpo-36138.yfjNzG.rst
@@ -0,0 +1 @@
+Improve documentation about converting datetime.timedelta to scalars.