[Python-checkins] peps: Update PEP-0424 with respect to feedback received.

alex.gaynor python-checkins at python.org
Mon Jul 30 03:10:53 CEST 2012


http://hg.python.org/peps/rev/055f717ee69a
changeset:   4492:055f717ee69a
parent:      4490:d4e77ba5329d
user:        Alex Gaynor <alex.gaynor at gmail.com>
date:        Mon Jul 16 20:00:55 2012 -0700
summary:
  Update PEP-0424 with respect to feedback received.

files:
  pep-0424.txt |  43 ++++++++++++++++++++++++++++++++++-----
  1 files changed, 37 insertions(+), 6 deletions(-)


diff --git a/pep-0424.txt b/pep-0424.txt
--- a/pep-0424.txt
+++ b/pep-0424.txt
@@ -15,7 +15,7 @@
 
 CPython currently defines an ``__length_hint__`` method on several types, such
 as various iterators. This method is then used by various other functions (such
-as ``map``) to presize lists based on the estimated returned by
+as ``list``) to presize lists based on the estimated returned by
 ``__length_hint__``. Types can then define ``__length_hint__`` which are not
 sized, and thus should not define ``__len__``, but can estimate or compute a
 size (such as many iterators).
@@ -26,11 +26,42 @@
 This PEP proposes formally documenting ``__length_hint__`` for other
 interpreter and non-standard library Python to implement.
 
-``__length_hint__`` must return an integer (else a TypeError is raised), and is
-not required to be accurate. It may return a value that is either larger or
-smaller than the actual size ofthe container. It may raise a ``TypeError`` if a
-specific instance cannot have its length estimated. It may not return a
-negative value (else a ValueError is raised).
+``__length_hint__`` must return an integer (else a TypeError is raised) or
+``NotImplemented, and is not required to be accurate. It may return a value
+that is either larger or smaller than the actual size ofthe container. A return value of ``NotImplemented`` indicates that there is no finite length estimate.
+It may not return a negative value (else a ValueError is raised).
+
+In addition, a new function ``operator.length`` hint is added, having the
+follow semantics (which define how ``__length_hint__`` should be used::
+
+    def length_hint(obj, default):
+        """
+        Return an estimate of the number of items in obj. This is
+        useful for presizing containers when building from an iterable.
+
+        If the object supports len(), the result will be exact. Otherwise, it
+        may over or underestimate by an arbitrary amount. The result will be an
+        integer >= 0.
+        """
+        try:
+            return len(obj)
+        except TypeError:
+            try:
+                get_hint = obj.__length_hint__
+            except AttributeError:
+                return default
+            hint = get_hint()
+            if hint is NotImplemented:
+                return default
+            if not isinstance(hint, int):
+                raise TypeError("Length hint must be an integer, not %r" % type(hint))
+            if hint < 0:
+                raise ValueError("Length hint (%r) must be >= 0" % hint)
+            return hint
+
+Callers are required to provide a default value, because there is no sane
+return value for objects which do not provide a length or length hint.
+
 
 Rationale
 =========

-- 
Repository URL: http://hg.python.org/peps


More information about the Python-checkins mailing list