[Python-checkins] python/dist/src/Doc/lib libfunctional.tex, NONE, 1.1 lib.tex, 1.237, 1.238

[rhettinger at users.sourceforge.net]

Update of /cvsroot/python/python/dist/src/Doc/lib
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv14403/Doc/lib

Modified Files:
	lib.tex 
Added Files:
	libfunctional.tex 
Log Message:
SF patch #941881:  PEP 309 Implementation (Partial Function Application).

Combined efforts of many including Peter Harris, Hye-Shik Chang, 
Martin v. Löwis, Nick Coghlan, Paul Moore, and Raymond Hettinger.



--- NEW FILE: libfunctional.tex ---
\section{\module{functional} ---
         Higher order functions and operations on callable objects.}

\declaremodule{standard}{functional}		% standard library, in Python

\moduleauthor{Peter Harris}{scav at blueyonder.co.uk}
\moduleauthor{Raymond Hettinger}{python at rcn.com}
\sectionauthor{Peter Harris}{scav at blueyonder.co.uk}

\modulesynopsis{Higher-order functions and operations on callable objects.}


The \module{functional} module is for higher-order functions: functions
that act on or return other functions. In general, any callable object can
be treated as a function for the purposes of this module.


The \module{functional} module defines the following function:

\begin{funcdesc}{partial}{func\optional{,*args}\optional{, **keywords}}
Return a new \class{partial} object which when called will behave like
\var{func} called with the positional arguments \var{args} and keyword
arguments \var{keywords}. If more arguments are supplied to the call, they
are appended to \var{args}. If additional keyword arguments are supplied,
they extend and override \var{keywords}. Roughly equivalent to:
  \begin{verbatim}
        def partial(func, *args, **keywords):
            def newfunc(*fargs, **fkeywords):
                newkeywords = keywords.copy()
                newkeywords.update(fkeywords)
                return func(*(args + fargs), **newkeywords)
            newfunc.func = func
            newfunc.args = args
            newfunc.keywords = keywords
            return newfunc
  \end{verbatim}

The \function{partial} is used for partial function application which
``freezes'' some portion of a function's arguments and/or keywords
resulting in an new object with a simplified signature.  For example,
\function{partial} can be used to create a callable that behaves like
the \function{int} function where the \var{base} argument defaults to
two:
  \begin{verbatim}
        >>> basetwo = partial(int, base=2)
        >>> basetwo('10010')
        18
  \end{verbatim}
\end{funcdesc}



\subsection{\class{partial} Objects \label{partial-objects}}


\class{partial} objects are callable objects created by \function{partial()}.
They have three read-only attributes:

\begin{memberdesc}[callable]{func}{}
A callable object or function.  Calls to the \class{partial} object will
be forwarded to \member{func} with new arguments and keywords.
\end{memberdesc}

\begin{memberdesc}[tuple]{args}{}
The leftmost positional arguments that will be prepended to the
positional arguments provided to a \class{partial} object call.
\end{memberdesc}

\begin{memberdesc}[dict]{keywords}{}
The keyword arguments that will be supplied when the \class{partial} object
is called.
\end{memberdesc}

Index: lib.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/lib/lib.tex,v
retrieving revision 1.237
retrieving revision 1.238
diff -u -d -r1.237 -r1.238
--- lib.tex	23 Jan 2005 09:27:23 -0000	1.237
+++ lib.tex	28 Feb 2005 19:39:23 -0000	1.238
@@ -132,6 +132,7 @@
 \input{libarray}
 \input{libsets}
 \input{libitertools}
+\input{libfunctional}
 \input{libcfgparser}
 \input{libfileinput}
 \input{libcalendar}