Abstract

CPython currently defines a__length_hint__ method on severaltypes, such as various iterators. This method is then used by variousother functions (such aslist) to presize lists based on theestimate returned by__length_hint__. Types which are not sized,and thus should not define__len__, can then define__length_hint__, to allow estimating or computing a size (such asmany iterators).

Specification

This PEP formally documents__length_hint__ for other interpretersand non-standard-library Python modules to implement.

__length_hint__ must return an integer (else aTypeError israised) orNotImplemented, and is not required to be accurate. Itmay return a value that is either larger or smaller than the actualsize of the container. A return value ofNotImplemented indicatesthat there is no finite length estimate. It may not return a negativevalue (else a ValueError is raised).

In addition, a new functionoperator.length_hint hint is added,with the following semantics (which define how__length_hint__should be used):

deflength_hint(obj,default=0):"""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 under-estimate by an    arbitrary amount. The result will be an integer >= 0.    """try:returnlen(obj)exceptTypeError:try:get_hint=type(obj).__length_hint__exceptAttributeError:returndefaulttry:hint=get_hint(obj)exceptTypeError:returndefaultifhintisNotImplemented:returndefaultifnotisinstance(hint,int):raiseTypeError("Length hint must be an integer, not%r"%type(hint))ifhint<0:raiseValueError("__length_hint__() should return >= 0")returnhint

Rationale

Being able to pre-allocate lists based on the expected size, asestimated by__length_hint__, can be a significant optimization.CPython has been observed to run some code faster than PyPy, purelybecause of this optimization being present.

Copyright

This document has been placed into the public domain.