http://hg.python.org/peps/rev/055f717ee69a changeset: 4492:055f717ee69a parent: 4490:d4e77ba5329d user: Alex Gaynor <alex.gaynor@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