add hg and python

1 files changed, 181 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libuserdict.tex b/sys/src/cmd/python/Doc/lib/libuserdict.tex
new file mode 100644
index 000000000..0bb57c826
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libuserdict.tex
@@ -0,0 +1,181 @@
+\section{\module{UserDict} ---
+         Class wrapper for dictionary objects}
+
+\declaremodule{standard}{UserDict}
+\modulesynopsis{Class wrapper for dictionary objects.}
+
+
+The module defines a mixin,  \class{DictMixin}, defining all dictionary
+methods for classes that already have a minimum mapping interface.  This
+greatly simplifies writing classes that need to be substitutable for
+dictionaries (such as the shelve module).
+
+This also module defines a class, \class{UserDict}, that acts as a wrapper
+around dictionary objects.  The need for this class has been largely
+supplanted by the ability to subclass directly from \class{dict} (a feature
+that became available starting with Python version 2.2).  Prior to the
+introduction of \class{dict}, the \class{UserDict} class was used to
+create dictionary-like sub-classes that obtained new behaviors by overriding
+existing methods or adding new ones.
+
+The \module{UserDict} module defines the \class{UserDict} class
+and \class{DictMixin}:
+
+\begin{classdesc}{UserDict}{\optional{initialdata}} 
+Class that simulates a dictionary.  The instance's contents are kept
+in a regular dictionary, which is accessible via the \member{data}
+attribute of \class{UserDict} instances.  If \var{initialdata} is
+provided, \member{data} is initialized with its contents; note that a
+reference to \var{initialdata} will not be kept, allowing it be used
+for other purposes. \note{For backward compatibility, instances of
+\class{UserDict} are not iterable.}
+\end{classdesc}
+
+\begin{classdesc}{IterableUserDict}{\optional{initialdata}}
+Subclass of \class{UserDict} that supports direct iteration (e.g. 
+\code{for key in myDict}).
+\end{classdesc}
+
+In addition to supporting the methods and operations of mappings (see
+section \ref{typesmapping}), \class{UserDict} and
+\class{IterableUserDict} instances provide the following attribute:
+
+\begin{memberdesc}{data}
+A real dictionary used to store the contents of the \class{UserDict}
+class.
+\end{memberdesc}
+
+\begin{classdesc}{DictMixin}{}
+Mixin defining all dictionary methods for classes that already have
+a minimum dictionary interface including \method{__getitem__()},
+\method{__setitem__()}, \method{__delitem__()}, and \method{keys()}.
+
+This mixin should be used as a superclass.  Adding each of the
+above methods adds progressively more functionality.  For instance,
+defining all but \method{__delitem__} will preclude only \method{pop}
+and \method{popitem} from the full interface.
+
+In addition to the four base methods, progressively more efficiency
+comes with defining \method{__contains__()}, \method{__iter__()}, and
+\method{iteritems()}.
+
+Since the mixin has no knowledge of the subclass constructor, it
+does not define \method{__init__()} or \method{copy()}.
+\end{classdesc}
+
+
+\section{\module{UserList} ---
+         Class wrapper for list objects}
+
+\declaremodule{standard}{UserList}
+\modulesynopsis{Class wrapper for list objects.}
+
+
+\note{This module is available for backward compatibility only.  If
+you are writing code that does not need to work with versions of
+Python earlier than Python 2.2, please consider subclassing directly
+from the built-in \class{list} type.}
+
+This module defines a class that acts as a wrapper around
+list objects.  It is a useful base class for
+your own list-like classes, which can inherit from
+them and override existing methods or add new ones.  In this way one
+can add new behaviors to lists.
+
+The \module{UserList} module defines the \class{UserList} class:
+
+\begin{classdesc}{UserList}{\optional{list}}
+Class that simulates a list.  The instance's
+contents are kept in a regular list, which is accessible via the
+\member{data} attribute of \class{UserList} instances.  The instance's
+contents are initially set to a copy of \var{list}, defaulting to the
+empty list \code{[]}.  \var{list} can be either a regular Python list,
+or an instance of \class{UserList} (or a subclass).
+\end{classdesc}
+
+In addition to supporting the methods and operations of mutable
+sequences (see section \ref{typesseq}), \class{UserList} instances
+provide the following attribute:
+
+\begin{memberdesc}{data}
+A real Python list object used to store the contents of the
+\class{UserList} class.
+\end{memberdesc}
+
+\strong{Subclassing requirements:}
+Subclasses of \class{UserList} are expect to offer a constructor which
+can be called with either no arguments or one argument.  List
+operations which return a new sequence attempt to create an instance
+of the actual implementation class.  To do so, it assumes that the
+constructor can be called with a single parameter, which is a sequence
+object used as a data source.
+
+If a derived class does not wish to comply with this requirement, all
+of the special methods supported by this class will need to be
+overridden; please consult the sources for information about the
+methods which need to be provided in that case.
+
+\versionchanged[Python versions 1.5.2 and 1.6 also required that the
+                constructor be callable with no parameters, and offer
+                a mutable \member{data} attribute.  Earlier versions
+                of Python did not attempt to create instances of the
+                derived class]{2.0}
+
+
+\section{\module{UserString} ---
+         Class wrapper for string objects}
+
+\declaremodule{standard}{UserString}
+\modulesynopsis{Class wrapper for string objects.}
+\moduleauthor{Peter Funk}{pf@artcom-gmbh.de}
+\sectionauthor{Peter Funk}{pf@artcom-gmbh.de}
+
+\note{This \class{UserString} class from this module is available for
+backward compatibility only.  If you are writing code that does not
+need to work with versions of Python earlier than Python 2.2, please
+consider subclassing directly from the built-in \class{str} type
+instead of using \class{UserString} (there is no built-in equivalent
+to \class{MutableString}).}
+
+This module defines a class that acts as a wrapper around string
+objects.  It is a useful base class for your own string-like classes,
+which can inherit from them and override existing methods or add new
+ones.  In this way one can add new behaviors to strings.
+
+It should be noted that these classes are highly inefficient compared
+to real string or Unicode objects; this is especially the case for
+\class{MutableString}.
+
+The \module{UserString} module defines the following classes:
+
+\begin{classdesc}{UserString}{\optional{sequence}}
+Class that simulates a string or a Unicode string
+object.  The instance's content is kept in a regular string or Unicode
+string object, which is accessible via the \member{data} attribute of
+\class{UserString} instances.  The instance's contents are initially
+set to a copy of \var{sequence}.  \var{sequence} can be either a
+regular Python string or Unicode string, an instance of
+\class{UserString} (or a subclass) or an arbitrary sequence which can
+be converted into a string using the built-in \function{str()} function.
+\end{classdesc}
+
+\begin{classdesc}{MutableString}{\optional{sequence}}
+This class is derived from the \class{UserString} above and redefines
+strings to be \emph{mutable}.  Mutable strings can't be used as
+dictionary keys, because dictionaries require \emph{immutable} objects as
+keys.  The main intention of this class is to serve as an educational
+example for inheritance and necessity to remove (override) the
+\method{__hash__()} method in order to trap attempts to use a
+mutable object as dictionary key, which would be otherwise very
+error prone and hard to track down.
+\end{classdesc}
+
+In addition to supporting the methods and operations of string and
+Unicode objects (see section \ref{string-methods}, ``String
+Methods''), \class{UserString} instances provide the following
+attribute:
+
+\begin{memberdesc}{data}
+A real Python string or Unicode object used to store the content of the
+\class{UserString} class.
+\end{memberdesc}