bpo-15718: Document the upper bound constrain on the __len__ return value. (#1256)

1 files changed, 9 insertions, 0 deletions

diff --git a/Doc/reference/datamodel.rst b/Doc/reference/datamodel.rst
index 095a2380b3..35925a065f 100644
--- a/Doc/reference/datamodel.rst
+++ b/Doc/reference/datamodel.rst
@@ -2011,6 +2011,14 @@ through the container; for mappings, :meth:`__iter__` should be the same as
    :meth:`__bool__` method and whose :meth:`__len__` method returns zero is
    considered to be false in a Boolean context.
 
+   .. impl-detail::
+
+      In CPython, the length is required to be at most :attr:`sys.maxsize`.
+      If the length is larger than :attr:`!sys.maxsize` some features (such as
+      :func:`len`) may raise :exc:`OverflowError`.  To prevent raising
+      :exc:`!OverflowError` by truth value testing, an object must define a
+      :meth:`__bool__` method.
+
 
 .. method:: object.__length_hint__(self)
 
@@ -2021,6 +2029,7 @@ through the container; for mappings, :meth:`__iter__` should be the same as
 
    .. versionadded:: 3.4
 
+
 .. note::
 
    Slicing is done exclusively with the following three methods.  A call like ::