add PEP 424 from Alex Gaynor

pep-0424.txt

@@ -0,0 +1,61 @@
+PEP: 424
+Title: A method for exposing a length hint
+Version: $Revision$
+Last-Modified: $Date
+Author: Alex Gaynor <alex.gaynor@gmail.com>
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created:
+Python-Version: Who knows!
+
+Abstract
+========
+
+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
+``__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).
+
+Proposal
+========
+
+This PEP proposes formally documenting ``__length_hint__`` for other
+interpreter and non-standard library Python to implement.
+
+``__length_hint__`` must return an integer, 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. It may raise a ``TypeError`` if a specific instance cannot have
+its length estimated. It may not return a negative value.
+
+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.
+
+Open questions
+==============
+
+There are two open questions for this PEP:
+
+* Should ``list`` expose a kwarg in it's constructor for supplying a length
+  hint.
+* Should a function be added either to ``builtins`` or some other module which
+  calls ``__length_hint__``, like ``builtins.len`` calls ``__len__``.
+
+Copyright
+=========
+
+This document has been placed into the public domain.
+
+..
+    Local Variables:
+    mode: indented-text
+    indent-tabs-mode: nil
+    sentence-end-double-space: t
+    fill-column: 70
+    coding: utf-8