diff --git a/pep-0424.txt b/pep-0424.txt index e0a873c98..803dad0f5 100644 --- a/pep-0424.txt +++ b/pep-0424.txt @@ -14,9 +14,9 @@ Abstract ======== CPython currently defines a ``__length_hint__`` method on several -types, such as various iterators. This method is then used by various +types, such as various iterators. This method is then used by various other functions (such as ``list``) to presize lists based on the -estimate returned by ``__length_hint__``. Types which are not sized, +estimate 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 as many iterators). @@ -24,18 +24,19 @@ many iterators). Specification ============= -This PEP formally documents ``__length_hint__`` for other -interpreters and non-standard-library Python modules to implement. +This PEP formally documents ``__length_hint__`` for other interpreters +and non-standard-library Python modules to implement. -``__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 of the 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). +``__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 of the 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`` hint is added, -with the following semantics (which define how ``__length_hint__`` should -be used):: +with the following semantics (which define how ``__length_hint__`` +should be used):: def length_hint(obj, default=0): """Return an estimate of the number of items in obj. @@ -71,10 +72,10 @@ be used):: Rationale ========= -Being able to pre-allocate lists based on the expected size, as estimated by -``__length_hint__``, can be a significant optimization. CPython has been -observed to run some code faster than PyPy, purely because of this optimization -being present. +Being able to pre-allocate lists based on the expected size, as +estimated by ``__length_hint__``, can be a significant optimization. +CPython has been observed to run some code faster than PyPy, purely +because of this optimization being present. Copyright =========