On Sat, May 25, 2013 at 4:16 PM, Łukasz Langa <luk...@langa.pl> wrote: > So, the latest document is live: > http://www.python.org/dev/peps/pep-0443/ > > The code is here: > http://hg.python.org/features/pep-443/file/tip/Lib/functools.py#l363 > > The documentation here: > http://hg.python.org/features/pep-443/file/tip/Doc/library/functools.rst#l189
Code and tests look great! Nitpick on the docs and PEP, though: generic functions are not composed of functions sharing the same name; it would probably be more correct to say they're composed of functions that perform the same operations on different types. (I think the "names" language might be left over from discussion of *overloaded* functions in PEP 3124 et al; in any case we're actually recommending people *not* use the same names now, so it's confusing.) We should probably also standardize on the term used for the registered functions. The standard terminology is "method", but that would be confusing in Python, where methods usually have a self argument. The PEP uses the term "implementation", and I think that actually makes a lot of sense: a generic function is composed of functions that implement the same operation for different types. So I suggest changing this: """ Transforms a function into a single-dispatch generic function. A **generic function** is composed of multiple functions sharing the same name. Which form should be used during a call is determined by the dispatch algorithm. When the implementation is chosen based on the type of a single argument, this is known as **single dispatch**. Adding an overload to a generic function is achieved by using the :func:`register` attribute of the generic function. The :func:`register` attribute is a decorator, taking a type paramater and decorating a function implementing the overload for that type.""" to: """ Transforms a function into a single-dispatch generic function. A **generic function** is composed of multiple functions implementing the same operation for different types. Which implementation should be used during a call is determined by the dispatch algorithm. When the implementation is chosen based on the type of a single argument, this is known as **single dispatch**. Adding an implementation to a generic function is achieved by using the :func:`register` attribute of the generic function. The :func:`register` attribute is a decorator, taking a type paramater and decorating a function implementing the operation for that type.""" And replacing "overload" with "implementation" in the remainder of the docs and code. Last, but not least, there should be a stacking example somewhere in the doc, as in the PEP, and perhaps the suggestion to name individual implementations differently from each other and the main function -- perhaps as an adjunct to documenting that register() always returns its argument unchanged. (Currently, it doesn't mention what register()'s return value is.) (It may also be useful to note somewhere that, due to caching, changing the base classes of an existing class may not change what implementation is selected the next time the generic function is invoked with an argument of that type or a subclass thereof.) _______________________________________________ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
