add hg and python

1 files changed, 530 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/liboperator.tex b/sys/src/cmd/python/Doc/lib/liboperator.tex
new file mode 100644
index 000000000..5ba3209be
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/liboperator.tex
@@ -0,0 +1,530 @@
+\section{\module{operator} ---
+         Standard operators as functions.}
+\declaremodule{builtin}{operator}
+\sectionauthor{Skip Montanaro}{skip@automatrix.com}
+
+\modulesynopsis{All Python's standard operators as built-in functions.}
+
+
+The \module{operator} module exports a set of functions implemented in C
+corresponding to the intrinsic operators of Python.  For example,
+\code{operator.add(x, y)} is equivalent to the expression \code{x+y}.  The
+function names are those used for special class methods; variants without
+leading and trailing \samp{__} are also provided for convenience.
+
+The functions fall into categories that perform object comparisons,
+logical operations, mathematical operations, sequence operations, and
+abstract type tests.
+
+The object comparison functions are useful for all objects, and are
+named after the rich comparison operators they support:
+
+\begin{funcdesc}{lt}{a, b}
+\funcline{le}{a, b}
+\funcline{eq}{a, b}
+\funcline{ne}{a, b}
+\funcline{ge}{a, b}
+\funcline{gt}{a, b}
+\funcline{__lt__}{a, b}
+\funcline{__le__}{a, b}
+\funcline{__eq__}{a, b}
+\funcline{__ne__}{a, b}
+\funcline{__ge__}{a, b}
+\funcline{__gt__}{a, b}
+Perform ``rich comparisons'' between \var{a} and \var{b}. Specifically,
+\code{lt(\var{a}, \var{b})} is equivalent to \code{\var{a} < \var{b}},
+\code{le(\var{a}, \var{b})} is equivalent to \code{\var{a} <= \var{b}},
+\code{eq(\var{a}, \var{b})} is equivalent to \code{\var{a} == \var{b}},
+\code{ne(\var{a}, \var{b})} is equivalent to \code{\var{a} != \var{b}},
+\code{gt(\var{a}, \var{b})} is equivalent to \code{\var{a} > \var{b}}
+and
+\code{ge(\var{a}, \var{b})} is equivalent to \code{\var{a} >= \var{b}}.
+Note that unlike the built-in \function{cmp()}, these functions can
+return any value, which may or may not be interpretable as a Boolean
+value.  See the \citetitle[../ref/ref.html]{Python Reference Manual}
+for more information about rich comparisons.
+\versionadded{2.2}
+\end{funcdesc}
+
+
+The logical operations are also generally applicable to all objects,
+and support truth tests, identity tests, and boolean operations:
+
+\begin{funcdesc}{not_}{o}
+\funcline{__not__}{o}
+Return the outcome of \keyword{not} \var{o}.  (Note that there is no
+\method{__not__()} method for object instances; only the interpreter
+core defines this operation.  The result is affected by the
+\method{__nonzero__()} and \method{__len__()} methods.)
+\end{funcdesc}
+
+\begin{funcdesc}{truth}{o}
+Return \constant{True} if \var{o} is true, and \constant{False}
+otherwise.  This is equivalent to using the \class{bool}
+constructor.
+\end{funcdesc}
+
+\begin{funcdesc}{is_}{a, b}
+Return \code{\var{a} is \var{b}}.  Tests object identity.
+\versionadded{2.3}
+\end{funcdesc}
+
+\begin{funcdesc}{is_not}{a, b}
+Return \code{\var{a} is not \var{b}}.  Tests object identity.
+\versionadded{2.3}
+\end{funcdesc}
+
+
+The mathematical and bitwise operations are the most numerous:
+
+\begin{funcdesc}{abs}{o}
+\funcline{__abs__}{o}
+Return the absolute value of \var{o}.
+\end{funcdesc}
+
+\begin{funcdesc}{add}{a, b}
+\funcline{__add__}{a, b}
+Return \var{a} \code{+} \var{b}, for \var{a} and \var{b} numbers.
+\end{funcdesc}
+
+\begin{funcdesc}{and_}{a, b}
+\funcline{__and__}{a, b}
+Return the bitwise and of \var{a} and \var{b}.
+\end{funcdesc}
+
+\begin{funcdesc}{div}{a, b}
+\funcline{__div__}{a, b}
+Return \var{a} \code{/} \var{b} when \code{__future__.division} is not
+in effect.  This is also known as ``classic'' division.
+\end{funcdesc}
+
+\begin{funcdesc}{floordiv}{a, b}
+\funcline{__floordiv__}{a, b}
+Return \var{a} \code{//} \var{b}.
+\versionadded{2.2}
+\end{funcdesc}
+
+\begin{funcdesc}{inv}{o}
+\funcline{invert}{o}
+\funcline{__inv__}{o}
+\funcline{__invert__}{o}
+Return the bitwise inverse of the number \var{o}.  This is equivalent
+to \code{\textasciitilde}\var{o}.  The names \function{invert()} and
+\function{__invert__()} were added in Python 2.0.
+\end{funcdesc}
+
+\begin{funcdesc}{lshift}{a, b}
+\funcline{__lshift__}{a, b}
+Return \var{a} shifted left by \var{b}.
+\end{funcdesc}
+
+\begin{funcdesc}{mod}{a, b}
+\funcline{__mod__}{a, b}
+Return \var{a} \code{\%} \var{b}.
+\end{funcdesc}
+
+\begin{funcdesc}{mul}{a, b}
+\funcline{__mul__}{a, b}
+Return \var{a} \code{*} \var{b}, for \var{a} and \var{b} numbers.
+\end{funcdesc}
+
+\begin{funcdesc}{neg}{o}
+\funcline{__neg__}{o}
+Return \var{o} negated.
+\end{funcdesc}
+
+\begin{funcdesc}{or_}{a, b}
+\funcline{__or__}{a, b}
+Return the bitwise or of \var{a} and \var{b}.
+\end{funcdesc}
+
+\begin{funcdesc}{pos}{o}
+\funcline{__pos__}{o}
+Return \var{o} positive.
+\end{funcdesc}
+
+\begin{funcdesc}{pow}{a, b}
+\funcline{__pow__}{a, b}
+Return \var{a} \code{**} \var{b}, for \var{a} and \var{b} numbers.
+\versionadded{2.3}
+\end{funcdesc}
+
+\begin{funcdesc}{rshift}{a, b}
+\funcline{__rshift__}{a, b}
+Return \var{a} shifted right by \var{b}.
+\end{funcdesc}
+
+\begin{funcdesc}{sub}{a, b}
+\funcline{__sub__}{a, b}
+Return \var{a} \code{-} \var{b}.
+\end{funcdesc}
+
+\begin{funcdesc}{truediv}{a, b}
+\funcline{__truediv__}{a, b}
+Return \var{a} \code{/} \var{b} when \code{__future__.division} is in
+effect.  This is also known as ``true'' division.
+\versionadded{2.2}
+\end{funcdesc}
+
+\begin{funcdesc}{xor}{a, b}
+\funcline{__xor__}{a, b}
+Return the bitwise exclusive or of \var{a} and \var{b}.
+\end{funcdesc}
+
+\begin{funcdesc}{index}{a}
+\funcline{__index__}{a}
+Return \var{a} converted to an integer.  Equivalent to \var{a}\code{.__index__()}.
+\versionadded{2.5}
+\end{funcdesc}
+
+Operations which work with sequences include:
+
+\begin{funcdesc}{concat}{a, b}
+\funcline{__concat__}{a, b}
+Return \var{a} \code{+} \var{b} for \var{a} and \var{b} sequences.
+\end{funcdesc}
+
+\begin{funcdesc}{contains}{a, b}
+\funcline{__contains__}{a, b}
+Return the outcome of the test \var{b} \code{in} \var{a}.
+Note the reversed operands.  The name \function{__contains__()} was
+added in Python 2.0.
+\end{funcdesc}
+
+\begin{funcdesc}{countOf}{a, b}
+Return the number of occurrences of \var{b} in \var{a}.
+\end{funcdesc}
+
+\begin{funcdesc}{delitem}{a, b}
+\funcline{__delitem__}{a, b}
+Remove the value of \var{a} at index \var{b}.
+\end{funcdesc}
+
+\begin{funcdesc}{delslice}{a, b, c}
+\funcline{__delslice__}{a, b, c}
+Delete the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
+\end{funcdesc}
+
+\begin{funcdesc}{getitem}{a, b}
+\funcline{__getitem__}{a, b}
+Return the value of \var{a} at index \var{b}.
+\end{funcdesc}
+
+\begin{funcdesc}{getslice}{a, b, c}
+\funcline{__getslice__}{a, b, c}
+Return the slice of \var{a} from index \var{b} to index \var{c}\code{-1}.
+\end{funcdesc}
+
+\begin{funcdesc}{indexOf}{a, b}
+Return the index of the first of occurrence of \var{b} in \var{a}.
+\end{funcdesc}
+
+\begin{funcdesc}{repeat}{a, b}
+\funcline{__repeat__}{a, b}
+Return \var{a} \code{*} \var{b} where \var{a} is a sequence and
+\var{b} is an integer.
+\end{funcdesc}
+
+\begin{funcdesc}{sequenceIncludes}{\unspecified}
+\deprecated{2.0}{Use \function{contains()} instead.}
+Alias for \function{contains()}.
+\end{funcdesc}
+
+\begin{funcdesc}{setitem}{a, b, c}
+\funcline{__setitem__}{a, b, c}
+Set the value of \var{a} at index \var{b} to \var{c}.
+\end{funcdesc}
+
+\begin{funcdesc}{setslice}{a, b, c, v}
+\funcline{__setslice__}{a, b, c, v}
+Set the slice of \var{a} from index \var{b} to index \var{c}\code{-1} to the
+sequence \var{v}.
+\end{funcdesc}
+
+
+Many operations have an ``in-place'' version.  The following functions
+provide a more primitive access to in-place operators than the usual
+syntax does; for example, the statement \code{x += y} is equivalent to
+\code{x = operator.iadd(x, y)}.  Another way to put it is to say that
+\code{z = operator.iadd(x, y)} is equivalent to the compound statement
+\code{z = x; z += y}.
+
+\begin{funcdesc}{iadd}{a, b}
+\funcline{__iadd__}{a, b}
+\code{a = iadd(a, b)} is equivalent to \code{a += b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{iand}{a, b}
+\funcline{__iand__}{a, b}
+\code{a = iand(a, b)} is equivalent to \code{a \&= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{iconcat}{a, b}
+\funcline{__iconcat__}{a, b}
+\code{a = iconcat(a, b)} is equivalent to \code{a += b} for \var{a}
+and \var{b} sequences.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{idiv}{a, b}
+\funcline{__idiv__}{a, b}
+\code{a = idiv(a, b)} is equivalent to \code{a /= b} when
+\code{__future__.division} is not in effect.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{ifloordiv}{a, b}
+\funcline{__ifloordiv__}{a, b}
+\code{a = ifloordiv(a, b)} is equivalent to \code{a //= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{ilshift}{a, b}
+\funcline{__ilshift__}{a, b}
+\code{a = ilshift(a, b)} is equivalent to \code{a <}\code{<= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{imod}{a, b}
+\funcline{__imod__}{a, b}
+\code{a = imod(a, b)} is equivalent to \code{a \%= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{imul}{a, b}
+\funcline{__imul__}{a, b}
+\code{a = imul(a, b)} is equivalent to \code{a *= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{ior}{a, b}
+\funcline{__ior__}{a, b}
+\code{a = ior(a, b)} is equivalent to \code{a |= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{ipow}{a, b}
+\funcline{__ipow__}{a, b}
+\code{a = ipow(a, b)} is equivalent to \code{a **= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{irepeat}{a, b}
+\funcline{__irepeat__}{a, b}
+\code{a = irepeat(a, b)} is equivalent to \code{a *= b} where
+\var{a} is a sequence and \var{b} is an integer.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{irshift}{a, b}
+\funcline{__irshift__}{a, b}
+\code{a = irshift(a, b)} is equivalent to \code{a >>= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{isub}{a, b}
+\funcline{__isub__}{a, b}
+\code{a = isub(a, b)} is equivalent to \code{a -= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{itruediv}{a, b}
+\funcline{__itruediv__}{a, b}
+\code{a = itruediv(a, b)} is equivalent to \code{a /= b} when
+\code{__future__.division} is in effect.
+\versionadded{2.5}
+\end{funcdesc}
+
+\begin{funcdesc}{ixor}{a, b}
+\funcline{__ixor__}{a, b}
+\code{a = ixor(a, b)} is equivalent to \code{a \textasciicircum= b}.
+\versionadded{2.5}
+\end{funcdesc}
+
+
+The \module{operator} module also defines a few predicates to test the
+type of objects.  \note{Be careful not to misinterpret the
+results of these functions; only \function{isCallable()} has any
+measure of reliability with instance objects.  For example:}
+
+\begin{verbatim}
+>>> class C:
+...     pass
+... 
+>>> import operator
+>>> o = C()
+>>> operator.isMappingType(o)
+True
+\end{verbatim}
+
+\begin{funcdesc}{isCallable}{o}
+\deprecated{2.0}{Use the \function{callable()} built-in function instead.}
+Returns true if the object \var{o} can be called like a function,
+otherwise it returns false.  True is returned for functions, bound and
+unbound methods, class objects, and instance objects which support the
+\method{__call__()} method.
+\end{funcdesc}
+
+\begin{funcdesc}{isMappingType}{o}
+Returns true if the object \var{o} supports the mapping interface.
+This is true for dictionaries and all instance objects defining
+\method{__getitem__}.
+\warning{There is no reliable way to test if an instance
+supports the complete mapping protocol since the interface itself is
+ill-defined.  This makes this test less useful than it otherwise might
+be.}
+\end{funcdesc}
+
+\begin{funcdesc}{isNumberType}{o}
+Returns true if the object \var{o} represents a number.  This is true
+for all numeric types implemented in C.
+\warning{There is no reliable way to test if an instance
+supports the complete numeric interface since the interface itself is
+ill-defined.  This makes this test less useful than it otherwise might
+be.}
+\end{funcdesc}
+
+\begin{funcdesc}{isSequenceType}{o}
+Returns true if the object \var{o} supports the sequence protocol.
+This returns true for all objects which define sequence methods in C,
+and for all instance objects defining \method{__getitem__}.
+\warning{There is no reliable
+way to test if an instance supports the complete sequence interface
+since the interface itself is ill-defined.  This makes this test less
+useful than it otherwise might be.}
+\end{funcdesc}
+
+
+Example: Build a dictionary that maps the ordinals from \code{0} to
+\code{255} to their character equivalents.
+
+\begin{verbatim}
+>>> import operator
+>>> d = {}
+>>> keys = range(256)
+>>> vals = map(chr, keys)
+>>> map(operator.setitem, [d]*len(keys), keys, vals)
+\end{verbatim}
+
+
+The \module{operator} module also defines tools for generalized attribute
+and item lookups.  These are useful for making fast field extractors
+as arguments for \function{map()}, \function{sorted()},
+\method{itertools.groupby()}, or other functions that expect a
+function argument.
+
+\begin{funcdesc}{attrgetter}{attr\optional{, args...}}
+Return a callable object that fetches \var{attr} from its operand.
+If more than one attribute is requested, returns a tuple of attributes.
+After, \samp{f=attrgetter('name')}, the call \samp{f(b)} returns
+\samp{b.name}.  After, \samp{f=attrgetter('name', 'date')}, the call
+\samp{f(b)} returns \samp{(b.name, b.date)}. 
+\versionadded{2.4}
+\versionchanged[Added support for multiple attributes]{2.5}
+\end{funcdesc}
+    
+\begin{funcdesc}{itemgetter}{item\optional{, args...}}
+Return a callable object that fetches \var{item} from its operand.
+If more than one item is requested, returns a tuple of items.
+After, \samp{f=itemgetter(2)}, the call \samp{f(b)} returns
+\samp{b[2]}.
+After, \samp{f=itemgetter(2,5,3)}, the call \samp{f(b)} returns
+\samp{(b[2], b[5], b[3])}.		
+\versionadded{2.4}
+\versionchanged[Added support for multiple item extraction]{2.5}		
+\end{funcdesc}
+
+Examples:
+                
+\begin{verbatim}
+>>> from operator import itemgetter
+>>> inventory = [('apple', 3), ('banana', 2), ('pear', 5), ('orange', 1)]
+>>> getcount = itemgetter(1)
+>>> map(getcount, inventory)
+[3, 2, 5, 1]
+>>> sorted(inventory, key=getcount)
+[('orange', 1), ('banana', 2), ('apple', 3), ('pear', 5)]
+\end{verbatim}
+                
+
+\subsection{Mapping Operators to Functions \label{operator-map}}
+
+This table shows how abstract operations correspond to operator
+symbols in the Python syntax and the functions in the
+\refmodule{operator} module.
+
+
+\begin{tableiii}{l|c|l}{textrm}{Operation}{Syntax}{Function}
+  \lineiii{Addition}{\code{\var{a} + \var{b}}}
+          {\code{add(\var{a}, \var{b})}}
+  \lineiii{Concatenation}{\code{\var{seq1} + \var{seq2}}}
+          {\code{concat(\var{seq1}, \var{seq2})}}
+  \lineiii{Containment Test}{\code{\var{o} in \var{seq}}}
+          {\code{contains(\var{seq}, \var{o})}}
+  \lineiii{Division}{\code{\var{a} / \var{b}}}
+          {\code{div(\var{a}, \var{b}) \#} without \code{__future__.division}}
+  \lineiii{Division}{\code{\var{a} / \var{b}}}
+          {\code{truediv(\var{a}, \var{b}) \#} with \code{__future__.division}}
+  \lineiii{Division}{\code{\var{a} // \var{b}}}
+          {\code{floordiv(\var{a}, \var{b})}}
+  \lineiii{Bitwise And}{\code{\var{a} \&\ \var{b}}}
+          {\code{and_(\var{a}, \var{b})}}
+  \lineiii{Bitwise Exclusive Or}{\code{\var{a} \^\ \var{b}}}
+          {\code{xor(\var{a}, \var{b})}}
+  \lineiii{Bitwise Inversion}{\code{\~{} \var{a}}}
+          {\code{invert(\var{a})}}
+  \lineiii{Bitwise Or}{\code{\var{a} | \var{b}}}
+          {\code{or_(\var{a}, \var{b})}}
+  \lineiii{Exponentiation}{\code{\var{a} ** \var{b}}}
+          {\code{pow(\var{a}, \var{b})}}
+  \lineiii{Identity}{\code{\var{a} is \var{b}}}
+          {\code{is_(\var{a}, \var{b})}}
+  \lineiii{Identity}{\code{\var{a} is not \var{b}}}
+          {\code{is_not(\var{a}, \var{b})}}
+  \lineiii{Indexed Assignment}{\code{\var{o}[\var{k}] = \var{v}}}
+          {\code{setitem(\var{o}, \var{k}, \var{v})}}
+  \lineiii{Indexed Deletion}{\code{del \var{o}[\var{k}]}}
+          {\code{delitem(\var{o}, \var{k})}}
+  \lineiii{Indexing}{\code{\var{o}[\var{k}]}}
+          {\code{getitem(\var{o}, \var{k})}}
+  \lineiii{Left Shift}{\code{\var{a} <\code{<} \var{b}}}
+          {\code{lshift(\var{a}, \var{b})}}
+  \lineiii{Modulo}{\code{\var{a} \%\ \var{b}}}
+          {\code{mod(\var{a}, \var{b})}}
+  \lineiii{Multiplication}{\code{\var{a} * \var{b}}}
+          {\code{mul(\var{a}, \var{b})}}
+  \lineiii{Negation (Arithmetic)}{\code{- \var{a}}}
+          {\code{neg(\var{a})}}
+  \lineiii{Negation (Logical)}{\code{not \var{a}}}
+          {\code{not_(\var{a})}}
+  \lineiii{Right Shift}{\code{\var{a} >> \var{b}}}
+          {\code{rshift(\var{a}, \var{b})}}
+  \lineiii{Sequence Repitition}{\code{\var{seq} * \var{i}}}
+          {\code{repeat(\var{seq}, \var{i})}}
+  \lineiii{Slice Assignment}{\code{\var{seq}[\var{i}:\var{j}]} = \var{values}}
+          {\code{setslice(\var{seq}, \var{i}, \var{j}, \var{values})}}
+  \lineiii{Slice Deletion}{\code{del \var{seq}[\var{i}:\var{j}]}}
+          {\code{delslice(\var{seq}, \var{i}, \var{j})}}
+  \lineiii{Slicing}{\code{\var{seq}[\var{i}:\var{j}]}}
+          {\code{getslice(\var{seq}, \var{i}, \var{j})}}
+  \lineiii{String Formatting}{\code{\var{s} \%\ \var{o}}}
+          {\code{mod(\var{s}, \var{o})}}
+  \lineiii{Subtraction}{\code{\var{a} - \var{b}}}
+          {\code{sub(\var{a}, \var{b})}}
+  \lineiii{Truth Test}{\code{\var{o}}}
+          {\code{truth(\var{o})}}
+  \lineiii{Ordering}{\code{\var{a} < \var{b}}}
+          {\code{lt(\var{a}, \var{b})}}
+  \lineiii{Ordering}{\code{\var{a} <= \var{b}}}
+          {\code{le(\var{a}, \var{b})}}
+  \lineiii{Equality}{\code{\var{a} == \var{b}}}
+          {\code{eq(\var{a}, \var{b})}}
+  \lineiii{Difference}{\code{\var{a} != \var{b}}}
+          {\code{ne(\var{a}, \var{b})}}
+  \lineiii{Ordering}{\code{\var{a} >= \var{b}}}
+          {\code{ge(\var{a}, \var{b})}}
+  \lineiii{Ordering}{\code{\var{a} > \var{b}}}
+          {\code{gt(\var{a}, \var{b})}}
+\end{tableiii}