add hg and python

1 files changed, 466 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libexcs.tex b/sys/src/cmd/python/Doc/lib/libexcs.tex
new file mode 100644
index 000000000..6d2a3c5d2
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libexcs.tex
@@ -0,0 +1,466 @@
+\section{Built-in Exceptions}
+
+\declaremodule{standard}{exceptions}
+\modulesynopsis{Standard exception classes.}
+
+
+Exceptions should be class objects.  
+The exceptions are defined in the module \module{exceptions}.  This
+module never needs to be imported explicitly: the exceptions are
+provided in the built-in namespace as well as the \module{exceptions}
+module.
+
+\begin{notice}
+In past versions of Python string exceptions were supported.  In
+Python 1.5 and newer versions, all standard exceptions have been
+converted to class objects and users are encouraged to do the same.
+String exceptions will raise a \code{DeprecationWarning} in Python 2.5 and
+newer.
+In future versions, support for string exceptions will be removed.
+
+Two distinct string objects with the same value are considered different
+exceptions.  This is done to force programmers to use exception names
+rather than their string value when specifying exception handlers.
+The string value of all built-in exceptions is their name, but this is
+not a requirement for user-defined exceptions or exceptions defined by
+library modules.
+\end{notice}
+
+For class exceptions, in a \keyword{try}\stindex{try} statement with
+an \keyword{except}\stindex{except} clause that mentions a particular
+class, that clause also handles any exception classes derived from
+that class (but not exception classes from which \emph{it} is
+derived).  Two exception classes that are not related via subclassing
+are never equivalent, even if they have the same name.
+
+The built-in exceptions listed below can be generated by the
+interpreter or built-in functions.  Except where mentioned, they have
+an ``associated value'' indicating the detailed cause of the error.
+This may be a string or a tuple containing several items of
+information (e.g., an error code and a string explaining the code).
+The associated value is the second argument to the
+\keyword{raise}\stindex{raise} statement.  For string exceptions, the
+associated value itself will be stored in the variable named as the
+second argument of the \keyword{except} clause (if any).  For class
+exceptions, that variable receives the exception instance.  If the
+exception class is derived from the standard root class
+\exception{BaseException}, the associated value is present as the
+exception instance's \member{args} attribute.  If there is a single argument
+(as is preferred), it is bound to the \member{message} attribute.
+
+User code can raise built-in exceptions.  This can be used to test an
+exception handler or to report an error condition ``just like'' the
+situation in which the interpreter raises the same exception; but
+beware that there is nothing to prevent user code from raising an
+inappropriate error.
+
+The built-in exception classes can be sub-classed to define new
+exceptions; programmers are encouraged to at least derive new
+exceptions from the \exception{Exception} class and not
+\exception{BaseException}.  More
+information on defining exceptions is available in the
+\citetitle[../tut/tut.html]{Python Tutorial} under the heading
+``User-defined Exceptions.''
+
+\setindexsubitem{(built-in exception base class)}
+
+The following exceptions are only used as base classes for other
+exceptions.
+
+\begin{excdesc}{BaseException}
+The base class for all built-in exceptions.  It is not meant to be directly
+inherited by user-defined classes (for that use \exception{Exception}).  If
+\function{str()} or \function{unicode()} is called on an instance of this
+class, the representation of the argument(s) to the instance are returned or
+the emptry string when there were no arguments.  If only a single argument is
+passed in, it is stored in the \member{message} attribute.  If more than one
+argument is passed in, \member{message} is set to the empty string.  These
+semantics are meant to reflect the fact that \member{message} is to store a
+text message explaining why the exception had been raised.  If more data needs
+to be attached to the exception, attach it through arbitrary attributes on the
+instance.  All arguments are also stored in \member{args} as a tuple, but it will
+eventually be deprecated and thus its use is discouraged.
+\versionadded{2.5}
+\end{excdesc}
+
+\begin{excdesc}{Exception}
+All built-in, non-system-exiting exceptions are derived
+from this class.  All user-defined exceptions should also be derived
+from this class.
+\versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
+\end{excdesc}
+
+\begin{excdesc}{StandardError}
+The base class for all built-in exceptions except
+\exception{StopIteration}, \exception{GeneratorExit},
+\exception{KeyboardInterrupt} and \exception{SystemExit}.
+\exception{StandardError} itself is derived from \exception{Exception}.
+\end{excdesc}
+
+\begin{excdesc}{ArithmeticError}
+The base class for those built-in exceptions that are raised for
+various arithmetic errors: \exception{OverflowError},
+\exception{ZeroDivisionError}, \exception{FloatingPointError}.
+\end{excdesc}
+
+\begin{excdesc}{LookupError}
+The base class for the exceptions that are raised when a key or
+index used on a mapping or sequence is invalid: \exception{IndexError},
+\exception{KeyError}.  This can be raised directly by
+\function{sys.setdefaultencoding()}.
+\end{excdesc}
+
+\begin{excdesc}{EnvironmentError}
+The base class for exceptions that
+can occur outside the Python system: \exception{IOError},
+\exception{OSError}.  When exceptions of this type are created with a
+2-tuple, the first item is available on the instance's \member{errno}
+attribute (it is assumed to be an error number), and the second item
+is available on the \member{strerror} attribute (it is usually the
+associated error message).  The tuple itself is also available on the
+\member{args} attribute.
+\versionadded{1.5.2}
+
+When an \exception{EnvironmentError} exception is instantiated with a
+3-tuple, the first two items are available as above, while the third
+item is available on the \member{filename} attribute.  However, for
+backwards compatibility, the \member{args} attribute contains only a
+2-tuple of the first two constructor arguments.
+
+The \member{filename} attribute is \code{None} when this exception is
+created with other than 3 arguments.  The \member{errno} and
+\member{strerror} attributes are also \code{None} when the instance was
+created with other than 2 or 3 arguments.  In this last case,
+\member{args} contains the verbatim constructor arguments as a tuple.
+\end{excdesc}
+
+
+\setindexsubitem{(built-in exception)}
+
+The following exceptions are the exceptions that are actually raised.
+
+\begin{excdesc}{AssertionError}
+\stindex{assert}
+Raised when an \keyword{assert} statement fails.
+\end{excdesc}
+
+\begin{excdesc}{AttributeError}
+% xref to attribute reference?
+  Raised when an attribute reference or assignment fails.  (When an
+  object does not support attribute references or attribute assignments
+  at all, \exception{TypeError} is raised.)
+\end{excdesc}
+
+\begin{excdesc}{EOFError}
+% XXXJH xrefs here
+  Raised when one of the built-in functions (\function{input()} or
+  \function{raw_input()}) hits an end-of-file condition (\EOF) without
+  reading any data.
+% XXXJH xrefs here
+  (N.B.: the \method{read()} and \method{readline()} methods of file
+  objects return an empty string when they hit \EOF.)
+\end{excdesc}
+
+\begin{excdesc}{FloatingPointError}
+  Raised when a floating point operation fails.  This exception is
+  always defined, but can only be raised when Python is configured
+  with the \longprogramopt{with-fpectl} option, or the
+  \constant{WANT_SIGFPE_HANDLER} symbol is defined in the
+  \file{pyconfig.h} file.
+\end{excdesc}
+
+\begin{excdesc}{GeneratorExit}
+  Raise when a generator's \method{close()} method is called.
+  It directly inherits from \exception{Exception} instead of
+  \exception{StandardError} since it is technically not an error.
+  \versionadded{2.5}
+\end{excdesc}
+
+\begin{excdesc}{IOError}
+% XXXJH xrefs here
+  Raised when an I/O operation (such as a \keyword{print} statement,
+  the built-in \function{open()} function or a method of a file
+  object) fails for an I/O-related reason, e.g., ``file not found'' or
+  ``disk full''.
+
+  This class is derived from \exception{EnvironmentError}.  See the
+  discussion above for more information on exception instance
+  attributes.
+\end{excdesc}
+
+\begin{excdesc}{ImportError}
+% XXXJH xref to import statement?
+  Raised when an \keyword{import} statement fails to find the module
+  definition or when a \code{from \textrm{\ldots} import} fails to find a
+  name that is to be imported.
+\end{excdesc}
+
+\begin{excdesc}{IndexError}
+% XXXJH xref to sequences
+  Raised when a sequence subscript is out of range.  (Slice indices are
+  silently truncated to fall in the allowed range; if an index is not a
+  plain integer, \exception{TypeError} is raised.)
+\end{excdesc}
+
+\begin{excdesc}{KeyError}
+% XXXJH xref to mapping objects?
+  Raised when a mapping (dictionary) key is not found in the set of
+  existing keys.
+\end{excdesc}
+
+\begin{excdesc}{KeyboardInterrupt}
+  Raised when the user hits the interrupt key (normally
+  \kbd{Control-C} or \kbd{Delete}).  During execution, a check for
+  interrupts is made regularly.
+% XXX(hylton) xrefs here
+  Interrupts typed when a built-in function \function{input()} or
+  \function{raw_input()} is waiting for input also raise this
+  exception.
+  The exception inherits from \exception{BaseException} so as to not be
+  accidentally caught by code that catches \exception{Exception} and thus
+  prevent the interpreter from exiting.
+  \versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
+\end{excdesc}
+
+\begin{excdesc}{MemoryError}
+  Raised when an operation runs out of memory but the situation may
+  still be rescued (by deleting some objects).  The associated value is
+  a string indicating what kind of (internal) operation ran out of memory.
+  Note that because of the underlying memory management architecture
+  (C's \cfunction{malloc()} function), the interpreter may not
+  always be able to completely recover from this situation; it
+  nevertheless raises an exception so that a stack traceback can be
+  printed, in case a run-away program was the cause.
+\end{excdesc}
+
+\begin{excdesc}{NameError}
+  Raised when a local or global name is not found.  This applies only
+  to unqualified names.  The associated value is an error message that
+  includes the name that could not be found.
+\end{excdesc}
+
+\begin{excdesc}{NotImplementedError}
+  This exception is derived from \exception{RuntimeError}.  In user
+  defined base classes, abstract methods should raise this exception
+  when they require derived classes to override the method.
+  \versionadded{1.5.2}
+\end{excdesc}
+
+\begin{excdesc}{OSError}
+  %xref for os module
+  This class is derived from \exception{EnvironmentError} and is used
+  primarily as the \refmodule{os} module's \code{os.error} exception.
+  See \exception{EnvironmentError} above for a description of the
+  possible associated values.
+  \versionadded{1.5.2}
+\end{excdesc}
+
+\begin{excdesc}{OverflowError}
+% XXXJH reference to long's and/or int's?
+  Raised when the result of an arithmetic operation is too large to be
+  represented.  This cannot occur for long integers (which would rather
+  raise \exception{MemoryError} than give up).  Because of the lack of
+  standardization of floating point exception handling in C, most
+  floating point operations also aren't checked.  For plain integers,
+  all operations that can overflow are checked except left shift, where
+  typical applications prefer to drop bits than raise an exception.
+\end{excdesc}
+
+\begin{excdesc}{ReferenceError}
+  This exception is raised when a weak reference proxy, created by the
+  \function{\refmodule{weakref}.proxy()} function, is used to access
+  an attribute of the referent after it has been garbage collected.
+  For more information on weak references, see the \refmodule{weakref}
+  module.
+  \versionadded[Previously known as the
+                \exception{\refmodule{weakref}.ReferenceError}
+                exception]{2.2}
+\end{excdesc}
+
+\begin{excdesc}{RuntimeError}
+  Raised when an error is detected that doesn't fall in any of the
+  other categories.  The associated value is a string indicating what
+  precisely went wrong.  (This exception is mostly a relic from a
+  previous version of the interpreter; it is not used very much any
+  more.)
+\end{excdesc}
+
+\begin{excdesc}{StopIteration}
+  Raised by an iterator's \method{next()} method to signal that there
+  are no further values.
+  This is derived from \exception{Exception} rather than
+  \exception{StandardError}, since this is not considered an error in
+  its normal application.
+  \versionadded{2.2}
+\end{excdesc}
+
+
+\begin{excdesc}{SyntaxError}
+% XXXJH xref to these functions?
+  Raised when the parser encounters a syntax error.  This may occur in
+  an \keyword{import} statement, in an \keyword{exec} statement, in a call
+  to the built-in function \function{eval()} or \function{input()}, or
+  when reading the initial script or standard input (also
+  interactively).
+
+  Instances of this class have attributes \member{filename},
+  \member{lineno}, \member{offset} and \member{text} for easier access
+  to the details.  \function{str()} of the exception instance returns
+  only the message.
+\end{excdesc}
+
+\begin{excdesc}{SystemError}
+  Raised when the interpreter finds an internal error, but the
+  situation does not look so serious to cause it to abandon all hope.
+  The associated value is a string indicating what went wrong (in
+  low-level terms).
+  
+  You should report this to the author or maintainer of your Python
+  interpreter.  Be sure to report the version of the Python
+  interpreter (\code{sys.version}; it is also printed at the start of an
+  interactive Python session), the exact error message (the exception's
+  associated value) and if possible the source of the program that
+  triggered the error.
+\end{excdesc}
+
+\begin{excdesc}{SystemExit}
+% XXX(hylton) xref to module sys?
+  This exception is raised by the \function{sys.exit()} function.  When it
+  is not handled, the Python interpreter exits; no stack traceback is
+  printed.  If the associated value is a plain integer, it specifies the
+  system exit status (passed to C's \cfunction{exit()} function); if it is
+  \code{None}, the exit status is zero; if it has another type (such as
+  a string), the object's value is printed and the exit status is one.
+
+  Instances have an attribute \member{code} which is set to the
+  proposed exit status or error message (defaulting to \code{None}).
+  Also, this exception derives directly from \exception{BaseException} and
+  not \exception{StandardError}, since it is not technically an error.
+
+  A call to \function{sys.exit()} is translated into an exception so that
+  clean-up handlers (\keyword{finally} clauses of \keyword{try} statements)
+  can be executed, and so that a debugger can execute a script without
+  running the risk of losing control.  The \function{os._exit()} function
+  can be used if it is absolutely positively necessary to exit
+  immediately (for example, in the child process after a call to
+  \function{fork()}).
+
+  The exception inherits from \exception{BaseException} instead of
+  \exception{StandardError} or \exception{Exception} so that it is not
+  accidentally caught by code that catches \exception{Exception}.  This allows
+  the exception to properly propagate up and cause the interpreter to exit.
+  \versionchanged[Changed to inherit from \exception{BaseException}]{2.5}
+\end{excdesc}
+
+\begin{excdesc}{TypeError}
+  Raised when an operation or function is applied to an object
+  of inappropriate type.  The associated value is a string giving
+  details about the type mismatch.
+\end{excdesc}
+
+\begin{excdesc}{UnboundLocalError}
+  Raised when a reference is made to a local variable in a function or
+  method, but no value has been bound to that variable.  This is a
+  subclass of \exception{NameError}.
+\versionadded{2.0}
+\end{excdesc}
+
+\begin{excdesc}{UnicodeError}
+  Raised when a Unicode-related encoding or decoding error occurs.  It
+  is a subclass of \exception{ValueError}.
+\versionadded{2.0}
+\end{excdesc}
+
+\begin{excdesc}{UnicodeEncodeError}
+  Raised when a Unicode-related error occurs during encoding.  It
+  is a subclass of \exception{UnicodeError}.
+\versionadded{2.3}
+\end{excdesc}
+
+\begin{excdesc}{UnicodeDecodeError}
+  Raised when a Unicode-related error occurs during decoding.  It
+  is a subclass of \exception{UnicodeError}.
+\versionadded{2.3}
+\end{excdesc}
+
+\begin{excdesc}{UnicodeTranslateError}
+  Raised when a Unicode-related error occurs during translating.  It
+  is a subclass of \exception{UnicodeError}.
+\versionadded{2.3}
+\end{excdesc}
+
+\begin{excdesc}{ValueError}
+  Raised when a built-in operation or function receives an argument
+  that has the right type but an inappropriate value, and the
+  situation is not described by a more precise exception such as
+  \exception{IndexError}.
+\end{excdesc}
+
+\begin{excdesc}{WindowsError}
+  Raised when a Windows-specific error occurs or when the error number
+  does not correspond to an \cdata{errno} value.  The
+  \member{winerror} and \member{strerror} values are created from the
+  return values of the \cfunction{GetLastError()} and
+  \cfunction{FormatMessage()} functions from the Windows Platform API.
+  The \member{errno} value maps the \member{winerror} value to 
+  corresponding \code{errno.h} values.
+  This is a subclass of \exception{OSError}.
+\versionadded{2.0}
+\versionchanged[Previous versions put the \cfunction{GetLastError()}
+codes into \member{errno}]{2.5}
+\end{excdesc}
+
+\begin{excdesc}{ZeroDivisionError}
+  Raised when the second argument of a division or modulo operation is
+  zero.  The associated value is a string indicating the type of the
+  operands and the operation.
+\end{excdesc}
+
+
+\setindexsubitem{(built-in warning)}
+
+The following exceptions are used as warning categories; see the
+\refmodule{warnings} module for more information.
+
+\begin{excdesc}{Warning}
+Base class for warning categories.
+\end{excdesc}
+
+\begin{excdesc}{UserWarning}
+Base class for warnings generated by user code.
+\end{excdesc}
+
+\begin{excdesc}{DeprecationWarning}
+Base class for warnings about deprecated features.
+\end{excdesc}
+
+\begin{excdesc}{PendingDeprecationWarning}
+Base class for warnings about features which will be deprecated in the future.
+\end{excdesc}
+
+\begin{excdesc}{SyntaxWarning}
+Base class for warnings about dubious syntax
+\end{excdesc}
+
+\begin{excdesc}{RuntimeWarning}
+Base class for warnings about dubious runtime behavior.
+\end{excdesc}
+
+\begin{excdesc}{FutureWarning}
+Base class for warnings about constructs that will change semantically
+in the future.
+\end{excdesc}
+
+\begin{excdesc}{ImportWarning}
+Base class for warnings about probable mistakes in module imports.
+\versionadded{2.5}
+\end{excdesc}
+
+\begin{excdesc}{UnicodeWarning}
+Base class for warnings related to Unicode.
+\versionadded{2.5}
+\end{excdesc}
+
+The class hierarchy for built-in exceptions is:
+
+\verbatiminput{../../Lib/test/exception_hierarchy.txt}