whatsnew: PEP 424 implementation.

Doc/c-api/object.rst

@@ -357,9 +357,9 @@ attribute is considered sufficient for this determination.
 
 .. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)
 
-   Return an estimated length for the object *o*. First trying to return its
+   Return an estimated length for the object *o*. First try to return its
-   actual length, then an estimate using ``__length_hint__``, and finally
+   actual length, then an estimate using :meth:`~object.__length_hint__`, and
-   returning the default value. On error ``-1`` is returned. This is the
+   finally return the default value. On error return ``-1``. This is the
    equivalent to the Python expression ``operator.length_hint(o, default)``.
 
    .. versionadded:: 3.4

Doc/library/operator.rst

@@ -240,9 +240,9 @@ their character equivalents.
 
 .. function:: length_hint(obj, default=0)
 
-   Return an estimated length for the object *o*. First trying to return its
+   Return an estimated length for the object *o*. First try to return its
    actual length, then an estimate using :meth:`object.__length_hint__`, and
-   finally returning the default value.
+   finally return the default value.
 
    .. versionadded:: 3.4
 

Doc/whatsnew/3.4.rst

@@ -393,6 +393,10 @@ Some smaller changes made to the core Python language are:
   several cases as a result of the introduction of Argument Clinic and other
   changes to the :mod:`inspect` and :mod:`pydoc` modules.
 
+* :meth:`~object.__length_hint__` is now part of the formal language
+  specification (see :pep:`424`).  (Contributed by Armin Ronacher in
+  :issue:`16148`.)
+
 
 New Modules
 ===========
@@ -1098,6 +1102,11 @@ There is now a pure-python version of the :mod:`operator` module available for
 reference and for use by alternate implementations of Python.  (Contributed by
 Zachary Ware in :issue:`16694`.)
 
+New function :func:`~operator.length_hint` provides an implementation of the
+specification for how the :meth:`~object.__length_hint__` special method should
+be used, as part of the :pep:`424` formal specification of this language
+feature.  (Contributed by Armin Ronacher in :issue:`16148`.)
+
 
 os
 --
@@ -1800,6 +1809,10 @@ Other Build and C API Changes
   <http://en.wikipedia.org/wiki/Data_Execution_Prevention>`_.  (Contributed by
   Christian Heimes in :issue:`16632`.)
 
+* New function :c:func:`PyObject_LengthHint` is the C API equivalent
+  of :func:`operator.length_hint`.  (Contributed by Armin Ronacher in
+  :issue:`16148`.)
+
 
 .. _other-improvements-3.4:
 

Misc/NEWS

@@ -2538,6 +2538,9 @@ Core and Builtins
 
 - Issue #16160: Subclass support now works for types.SimpleNamespace.
 
+- Issue #16148: Implement PEP 424, adding operator.length_hint and
+  PyObject_LengthHint.
+
 - Upgrade Unicode data (UCD) to version 6.2.
 
 - Issue #15379: Fix passing of non-BMP characters as integers for the charmap