[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