Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libfunctional.tex @ 37850:ebe59cd18273

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Use explicit relative import for an, ehm, relative import.
author Thomas Wouters <thomas@python.org>
date Tue, 18 Apr 2006 21:41:36 +0000
parents b77edcee888c
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
34636
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
1 \section{\module{functional} ---
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
2 Higher order functions and operations on callable objects.}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
3
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
4 \declaremodule{standard}{functional} % standard library, in Python
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
5
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
6 \moduleauthor{Peter Harris}{scav@blueyonder.co.uk}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
7 \moduleauthor{Raymond Hettinger}{python@rcn.com}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
8 \sectionauthor{Peter Harris}{scav@blueyonder.co.uk}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
9
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
10 \modulesynopsis{Higher-order functions and operations on callable objects.}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
11
34646
b4315e67edf5 Noted that the module is new in version 2.5.
Raymond Hettinger <python@rcn.com>
parents: 34636
diff changeset
12 \versionadded{2.5}
34636
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
13
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
14 The \module{functional} module is for higher-order functions: functions
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
15 that act on or return other functions. In general, any callable object can
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
16 be treated as a function for the purposes of this module.
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
17
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
18
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
19 The \module{functional} module defines the following function:
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
20
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
21 \begin{funcdesc}{partial}{func\optional{,*args}\optional{, **keywords}}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
22 Return a new \class{partial} object which when called will behave like
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
23 \var{func} called with the positional arguments \var{args} and keyword
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
24 arguments \var{keywords}. If more arguments are supplied to the call, they
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
25 are appended to \var{args}. If additional keyword arguments are supplied,
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
26 they extend and override \var{keywords}. Roughly equivalent to:
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
27 \begin{verbatim}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
28 def partial(func, *args, **keywords):
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
29 def newfunc(*fargs, **fkeywords):
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
30 newkeywords = keywords.copy()
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
31 newkeywords.update(fkeywords)
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
32 return func(*(args + fargs), **newkeywords)
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
33 newfunc.func = func
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
34 newfunc.args = args
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
35 newfunc.keywords = keywords
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
36 return newfunc
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
37 \end{verbatim}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
38
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
39 The \function{partial} is used for partial function application which
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
40 ``freezes'' some portion of a function's arguments and/or keywords
34906
fc442c2eb0cf SF patch #1180062 by George Yoshida:
Walter Dörwald <walter@livinglogic.de>
parents: 34704
diff changeset
41 resulting in a new object with a simplified signature. For example,
34636
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
42 \function{partial} can be used to create a callable that behaves like
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
43 the \function{int} function where the \var{base} argument defaults to
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
44 two:
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
45 \begin{verbatim}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
46 >>> basetwo = partial(int, base=2)
35995
b77edcee888c Typo in a code example.
Armin Rigo <arigo@tunes.org>
parents: 34906
diff changeset
47 >>> basetwo.__doc__ = 'Convert base 2 string to an int.'
34636
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
48 >>> basetwo('10010')
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
49 18
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
50 \end{verbatim}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
51 \end{funcdesc}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
52
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
53
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
54
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
55 \subsection{\class{partial} Objects \label{partial-objects}}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
56
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
57
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
58 \class{partial} objects are callable objects created by \function{partial()}.
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
59 They have three read-only attributes:
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
60
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
61 \begin{memberdesc}[callable]{func}{}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
62 A callable object or function. Calls to the \class{partial} object will
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
63 be forwarded to \member{func} with new arguments and keywords.
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
64 \end{memberdesc}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
65
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
66 \begin{memberdesc}[tuple]{args}{}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
67 The leftmost positional arguments that will be prepended to the
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
68 positional arguments provided to a \class{partial} object call.
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
69 \end{memberdesc}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
70
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
71 \begin{memberdesc}[dict]{keywords}{}
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
72 The keyword arguments that will be supplied when the \class{partial} object
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
73 is called.
3d0bb3b05d39 SF patch #941881: PEP 309 Implementation (Partial Function Application).
Raymond Hettinger <python@rcn.com>
parents:
diff changeset
74 \end{memberdesc}
34704
3098efe42a0f Make functional.partial() more closely match the spec by emulating some useful features of regular functions:
Raymond Hettinger <python@rcn.com>
parents: 34646
diff changeset
75
3098efe42a0f Make functional.partial() more closely match the spec by emulating some useful features of regular functions:
Raymond Hettinger <python@rcn.com>
parents: 34646
diff changeset
76 \class{partial} objects are like \class{function} objects in that they are
3098efe42a0f Make functional.partial() more closely match the spec by emulating some useful features of regular functions:
Raymond Hettinger <python@rcn.com>
parents: 34646
diff changeset
77 callable, weak referencable, and can have attributes. There are some
3098efe42a0f Make functional.partial() more closely match the spec by emulating some useful features of regular functions:
Raymond Hettinger <python@rcn.com>
parents: 34646
diff changeset
78 important differences. For instance, the \member{__name__} and
3098efe42a0f Make functional.partial() more closely match the spec by emulating some useful features of regular functions:
Raymond Hettinger <python@rcn.com>
parents: 34646
diff changeset
79 \member{__doc__} attributes are not created automatically. Also,
3098efe42a0f Make functional.partial() more closely match the spec by emulating some useful features of regular functions:
Raymond Hettinger <python@rcn.com>
parents: 34646
diff changeset
80 \class{partial} objects defined in classes behave like static methods and
3098efe42a0f Make functional.partial() more closely match the spec by emulating some useful features of regular functions:
Raymond Hettinger <python@rcn.com>
parents: 34646
diff changeset
81 do not transform into bound methods during instance attribute look-up.