add hg and python

1 files changed, 442 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/api/exceptions.tex b/sys/src/cmd/python/Doc/api/exceptions.tex
new file mode 100644
index 000000000..2dabeee62
--- /dev/null
+++ b/sys/src/cmd/python/Doc/api/exceptions.tex
@@ -0,0 +1,442 @@
+\chapter{Exception Handling \label{exceptionHandling}}
+
+The functions described in this chapter will let you handle and raise Python
+exceptions.  It is important to understand some of the basics of
+Python exception handling.  It works somewhat like the
+\UNIX{} \cdata{errno} variable: there is a global indicator (per
+thread) of the last error that occurred.  Most functions don't clear
+this on success, but will set it to indicate the cause of the error on
+failure.  Most functions also return an error indicator, usually
+\NULL{} if they are supposed to return a pointer, or \code{-1} if they
+return an integer (exception: the \cfunction{PyArg_*()} functions
+return \code{1} for success and \code{0} for failure).
+
+When a function must fail because some function it called failed, it
+generally doesn't set the error indicator; the function it called
+already set it.  It is responsible for either handling the error and
+clearing the exception or returning after cleaning up any resources it
+holds (such as object references or memory allocations); it should
+\emph{not} continue normally if it is not prepared to handle the
+error.  If returning due to an error, it is important to indicate to
+the caller that an error has been set.  If the error is not handled or
+carefully propagated, additional calls into the Python/C API may not
+behave as intended and may fail in mysterious ways.
+
+The error indicator consists of three Python objects corresponding to
+\withsubitem{(in module sys)}{
+  \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
+the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
+\code{sys.exc_traceback}.  API functions exist to interact with the
+error indicator in various ways.  There is a separate error indicator
+for each thread.
+
+% XXX Order of these should be more thoughtful.
+% Either alphabetical or some kind of structure.
+
+\begin{cfuncdesc}{void}{PyErr_Print}{}
+  Print a standard traceback to \code{sys.stderr} and clear the error
+  indicator.  Call this function only when the error indicator is
+  set.  (Otherwise it will cause a fatal error!)
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{}
+  Test whether the error indicator is set.  If set, return the
+  exception \emph{type} (the first argument to the last call to one of
+  the \cfunction{PyErr_Set*()} functions or to
+  \cfunction{PyErr_Restore()}).  If not set, return \NULL.  You do
+  not own a reference to the return value, so you do not need to
+  \cfunction{Py_DECREF()} it.  \note{Do not compare the return value
+    to a specific exception; use \cfunction{PyErr_ExceptionMatches()}
+    instead, shown below.  (The comparison could easily fail since the
+    exception may be an instance instead of a class, in the case of a
+    class exception, or it may the a subclass of the expected
+    exception.)}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
+  Equivalent to \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(),
+  \var{exc})}.  This should only be called when an exception is
+  actually set; a memory access violation will occur if no exception
+  has been raised.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
+  Return true if the \var{given} exception matches the exception in
+  \var{exc}.  If \var{exc} is a class object, this also returns true
+  when \var{given} is an instance of a subclass.  If \var{exc} is a
+  tuple, all exceptions in the tuple (and recursively in subtuples)
+  are searched for a match.  If \var{given} is \NULL, a memory access
+  violation will occur.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
+  Under certain circumstances, the values returned by
+  \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning
+  that \code{*\var{exc}} is a class object but \code{*\var{val}} is
+  not an instance of the  same class.  This function can be used to
+  instantiate the class in that case.  If the values are already
+  normalized, nothing happens.  The delayed normalization is
+  implemented to improve performance.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_Clear}{}
+  Clear the error indicator.  If the error indicator is not set, there
+  is no effect.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue,
+                                     PyObject **ptraceback}
+  Retrieve the error indicator into three variables whose addresses
+  are passed.  If the error indicator is not set, set all three
+  variables to \NULL.  If it is set, it will be cleared and you own a
+  reference to each object retrieved.  The value and traceback object
+  may be \NULL{} even when the type object is not.  \note{This
+  function is normally only used by code that needs to handle
+  exceptions or by code that needs to save and restore the error
+  indicator temporarily.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value,
+                                       PyObject *traceback}
+  Set  the error indicator from the three objects.  If the error
+  indicator is already set, it is cleared first.  If the objects are
+  \NULL, the error indicator is cleared.  Do not pass a \NULL{} type
+  and non-\NULL{} value or traceback.  The exception type should be a
+  class.  Do not pass an invalid exception type or value.
+  (Violating these rules will cause subtle problems later.)  This call
+  takes away a reference to each object: you must own a reference to
+  each object before the call and after the call you no longer own
+  these references.  (If you don't understand this, don't use this
+  function.  I warned you.)  \note{This function is normally only used
+  by code that needs to save and restore the error indicator
+  temporarily; use \cfunction{PyErr_Fetch()} to save the current
+  exception state.}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, const char *message}
+  This is the most common way to set the error indicator.  The first
+  argument specifies the exception type; it is normally one of the
+  standard exceptions, e.g. \cdata{PyExc_RuntimeError}.  You need not
+  increment its reference count.  The second argument is an error
+  message; it is converted to a string object.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
+  This function is similar to \cfunction{PyErr_SetString()} but lets
+  you specify an arbitrary Python object for the ``value'' of the
+  exception.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
+                                           const char *format, \moreargs}
+  This function sets the error indicator and returns \NULL.
+  \var{exception} should be a Python exception (class, not
+  an instance).  \var{format} should be a string, containing format
+  codes, similar to \cfunction{printf()}. The \code{width.precision}
+  before a format code is parsed, but the width part is ignored.
+
+  % This should be exactly the same as the table in PyString_FromFormat.
+  % One should just refer to the other.
+
+  % The descriptions for %zd and %zu are wrong, but the truth is complicated
+  % because not all compilers support the %z width modifier -- we fake it
+  % when necessary via interpolating PY_FORMAT_SIZE_T.
+
+  % %u, %lu, %zu should have "new in Python 2.5" blurbs.
+
+  \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
+    \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
+    \lineiii{\%c}{int}{A single character, represented as an C int.}
+    \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
+    \lineiii{\%u}{unsigned int}{Exactly equivalent to \code{printf("\%u")}.}
+    \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
+    \lineiii{\%lu}{unsigned long}{Exactly equivalent to \code{printf("\%lu")}.}
+    \lineiii{\%zd}{Py_ssize_t}{Exactly equivalent to \code{printf("\%zd")}.}
+    \lineiii{\%zu}{size_t}{Exactly equivalent to \code{printf("\%zu")}.}
+    \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
+    \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
+    \lineiii{\%s}{char*}{A null-terminated C character array.}
+    \lineiii{\%p}{void*}{The hex representation of a C pointer.
+	Mostly equivalent to \code{printf("\%p")} except that it is
+	guaranteed to start with the literal \code{0x} regardless of
+	what the platform's \code{printf} yields.}
+  \end{tableiii}
+
+  An unrecognized format character causes all the rest of the format
+  string to be copied as-is to the result string, and any extra
+  arguments discarded.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
+  This is a shorthand for \samp{PyErr_SetObject(\var{type},
+  Py_None)}.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_BadArgument}{}
+  This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
+  \var{message})}, where \var{message} indicates that a built-in
+  operation was invoked with an illegal argument.  It is mostly for
+  internal use.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
+  This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
+  returns \NULL{} so an object allocation function can write
+  \samp{return PyErr_NoMemory();} when it runs out of memory.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type}
+  This is a convenience function to raise an exception when a C
+  library function has returned an error and set the C variable
+  \cdata{errno}.  It constructs a tuple object whose first item is the
+  integer \cdata{errno} value and whose second item is the
+  corresponding error message (gotten from
+  \cfunction{strerror()}\ttindex{strerror()}), and then calls
+  \samp{PyErr_SetObject(\var{type}, \var{object})}.  On \UNIX, when
+  the \cdata{errno} value is \constant{EINTR}, indicating an
+  interrupted system call, this calls
+  \cfunction{PyErr_CheckSignals()}, and if that set the error
+  indicator, leaves it set to that.  The function always returns
+  \NULL, so a wrapper function around a system call can write
+  \samp{return PyErr_SetFromErrno(\var{type});} when the system call
+  returns an error.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type,
+                                                             const char *filename}
+  Similar to \cfunction{PyErr_SetFromErrno()}, with the additional
+  behavior that if \var{filename} is not \NULL, it is passed to the
+  constructor of \var{type} as a third parameter.  In the case of
+  exceptions such as \exception{IOError} and \exception{OSError}, this
+  is used to define the \member{filename} attribute of the exception
+  instance.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErr}{int ierr}
+  This is a convenience function to raise \exception{WindowsError}.
+  If called with \var{ierr} of \cdata{0}, the error code returned by a
+  call to \cfunction{GetLastError()} is used instead.  It calls the
+  Win32 function \cfunction{FormatMessage()} to retrieve the Windows
+  description of error code given by \var{ierr} or
+  \cfunction{GetLastError()}, then it constructs a tuple object whose
+  first item is the \var{ierr} value and whose second item is the
+  corresponding error message (gotten from
+  \cfunction{FormatMessage()}), and then calls
+  \samp{PyErr_SetObject(\var{PyExc_WindowsError}, \var{object})}.
+  This function always returns \NULL.
+  Availability: Windows.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErr}{PyObject *type,
+	                                                 int ierr}
+  Similar to \cfunction{PyErr_SetFromWindowsErr()}, with an additional
+  parameter specifying the exception type to be raised.
+  Availability: Windows.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetFromWindowsErrWithFilename}{int ierr,
+                                                                const char *filename}
+  Similar to \cfunction{PyErr_SetFromWindowsErr()}, with the
+  additional behavior that if \var{filename} is not \NULL, it is
+  passed to the constructor of \exception{WindowsError} as a third
+  parameter.
+  Availability: Windows.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_SetExcFromWindowsErrWithFilename}
+	{PyObject *type, int ierr, char *filename}
+  Similar to \cfunction{PyErr_SetFromWindowsErrWithFilename()}, with
+  an additional parameter specifying the exception type to be raised.
+  Availability: Windows.
+  \versionadded{2.3}
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
+  This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
+  \var{message})}, where \var{message} indicates that an internal
+  operation (e.g. a Python/C API function) was invoked with an illegal
+  argument.  It is mostly for internal use.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_WarnEx}{PyObject *category, char *message, int stacklevel}
+  Issue a warning message.  The \var{category} argument is a warning
+  category (see below) or \NULL; the \var{message} argument is a
+  message string.  \var{stacklevel} is a positive number giving a
+  number of stack frames; the warning will be issued from the 
+  currently executing line of code in that stack frame.  A \var{stacklevel}
+  of 1 is the function calling \cfunction{PyErr_WarnEx()}, 2 is 
+  the function above that, and so forth.
+
+  This function normally prints a warning message to \var{sys.stderr};
+  however, it is also possible that the user has specified that
+  warnings are to be turned into errors, and in that case this will
+  raise an exception.  It is also possible that the function raises an
+  exception because of a problem with the warning machinery (the
+  implementation imports the \module{warnings} module to do the heavy
+  lifting).  The return value is \code{0} if no exception is raised,
+  or \code{-1} if an exception is raised.  (It is not possible to
+  determine whether a warning message is actually printed, nor what
+  the reason is for the exception; this is intentional.)  If an
+  exception is raised, the caller should do its normal exception
+  handling (for example, \cfunction{Py_DECREF()} owned references and
+  return an error value).
+
+  Warning categories must be subclasses of \cdata{Warning}; the
+  default warning category is \cdata{RuntimeWarning}.  The standard
+  Python warning categories are available as global variables whose
+  names are \samp{PyExc_} followed by the Python exception name.
+  These have the type \ctype{PyObject*}; they are all class objects.
+  Their names are \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
+  \cdata{PyExc_UnicodeWarning}, \cdata{PyExc_DeprecationWarning},
+  \cdata{PyExc_SyntaxWarning}, \cdata{PyExc_RuntimeWarning}, and
+  \cdata{PyExc_FutureWarning}.  \cdata{PyExc_Warning} is a subclass of
+  \cdata{PyExc_Exception}; the other warning categories are subclasses
+  of \cdata{PyExc_Warning}.
+
+  For information about warning control, see the documentation for the
+  \module{warnings} module and the \programopt{-W} option in the
+  command line documentation.  There is no C API for warning control.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
+  Issue a warning message.  The \var{category} argument is a warning
+  category (see below) or \NULL; the \var{message} argument is a
+  message string.  The warning will appear to be issued from the function
+  calling \cfunction{PyErr_Warn()}, equivalent to calling
+  \cfunction{PyErr_WarnEx()} with a \var{stacklevel} of 1.
+  
+  Deprecated; use \cfunction{PyErr_WarnEx()} instead.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category,
+                const char *message, const char *filename, int lineno,
+                const char *module, PyObject *registry}
+  Issue a warning message with explicit control over all warning
+  attributes.  This is a straightforward wrapper around the Python
+  function \function{warnings.warn_explicit()}, see there for more
+  information.  The \var{module} and \var{registry} arguments may be
+  set to \NULL{} to get the default effect described there.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
+  This function interacts with Python's signal handling.  It checks
+  whether a signal has been sent to the processes and if so, invokes
+  the corresponding signal handler.  If the
+  \module{signal}\refbimodindex{signal} module is supported, this can
+  invoke a signal handler written in Python.  In all cases, the
+  default effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the
+  \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
+  \exception{KeyboardInterrupt} exception.  If an exception is raised
+  the error indicator is set and the function returns \code{-1};
+  otherwise the function returns \code{0}.  The error indicator may or
+  may not be cleared if it was previously set.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
+  This function simulates the effect of a
+  \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time
+  \cfunction{PyErr_CheckSignals()} is called,
+  \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
+  \exception{KeyboardInterrupt} will be raised.  It may be called
+  without holding the interpreter lock.
+  % XXX This was described as obsolete, but is used in
+  % thread.interrupt_main() (used from IDLE), so it's still needed.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
+                                                 PyObject *base,
+                                                 PyObject *dict}
+  This utility function creates and returns a new exception object.
+  The \var{name} argument must be the name of the new exception, a C
+  string of the form \code{module.class}.  The \var{base} and
+  \var{dict} arguments are normally \NULL.  This creates a class
+  object derived from \exception{Exception} (accessible in C as
+  \cdata{PyExc_Exception}).
+
+  The \member{__module__} attribute of the new class is set to the
+  first part (up to the last dot) of the \var{name} argument, and the
+  class name is set to the last part (after the last dot).  The
+  \var{base} argument can be used to specify alternate base classes;
+  it can either be only one class or a tuple of classes.
+  The \var{dict} argument can be used to specify a dictionary of class
+  variables and methods.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj}
+  This utility function prints a warning message to \code{sys.stderr}
+  when an exception has been set but it is impossible for the
+  interpreter to actually raise the exception.  It is used, for
+  example, when an exception occurs in an \method{__del__()} method.
+
+  The function is called with a single argument \var{obj} that
+  identifies the context in which the unraisable exception occurred.
+  The repr of \var{obj} will be printed in the warning message.
+\end{cfuncdesc}
+
+\section{Standard Exceptions \label{standardExceptions}}
+
+All standard Python exceptions are available as global variables whose
+names are \samp{PyExc_} followed by the Python exception name.  These
+have the type \ctype{PyObject*}; they are all class objects.  For
+completeness, here are all the variables:
+
+\begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes}
+  \lineiii{PyExc_BaseException\ttindex{PyExc_BaseException}}{\exception{BaseException}}{(1), (4)}
+  \lineiii{PyExc_Exception\ttindex{PyExc_Exception}}{\exception{Exception}}{(1)}
+  \lineiii{PyExc_StandardError\ttindex{PyExc_StandardError}}{\exception{StandardError}}{(1)}
+  \lineiii{PyExc_ArithmeticError\ttindex{PyExc_ArithmeticError}}{\exception{ArithmeticError}}{(1)}
+  \lineiii{PyExc_LookupError\ttindex{PyExc_LookupError}}{\exception{LookupError}}{(1)}
+  \lineiii{PyExc_AssertionError\ttindex{PyExc_AssertionError}}{\exception{AssertionError}}{}
+  \lineiii{PyExc_AttributeError\ttindex{PyExc_AttributeError}}{\exception{AttributeError}}{}
+  \lineiii{PyExc_EOFError\ttindex{PyExc_EOFError}}{\exception{EOFError}}{}
+  \lineiii{PyExc_EnvironmentError\ttindex{PyExc_EnvironmentError}}{\exception{EnvironmentError}}{(1)}
+  \lineiii{PyExc_FloatingPointError\ttindex{PyExc_FloatingPointError}}{\exception{FloatingPointError}}{}
+  \lineiii{PyExc_IOError\ttindex{PyExc_IOError}}{\exception{IOError}}{}
+  \lineiii{PyExc_ImportError\ttindex{PyExc_ImportError}}{\exception{ImportError}}{}
+  \lineiii{PyExc_IndexError\ttindex{PyExc_IndexError}}{\exception{IndexError}}{}
+  \lineiii{PyExc_KeyError\ttindex{PyExc_KeyError}}{\exception{KeyError}}{}
+  \lineiii{PyExc_KeyboardInterrupt\ttindex{PyExc_KeyboardInterrupt}}{\exception{KeyboardInterrupt}}{}
+  \lineiii{PyExc_MemoryError\ttindex{PyExc_MemoryError}}{\exception{MemoryError}}{}
+  \lineiii{PyExc_NameError\ttindex{PyExc_NameError}}{\exception{NameError}}{}
+  \lineiii{PyExc_NotImplementedError\ttindex{PyExc_NotImplementedError}}{\exception{NotImplementedError}}{}
+  \lineiii{PyExc_OSError\ttindex{PyExc_OSError}}{\exception{OSError}}{}
+  \lineiii{PyExc_OverflowError\ttindex{PyExc_OverflowError}}{\exception{OverflowError}}{}
+  \lineiii{PyExc_ReferenceError\ttindex{PyExc_ReferenceError}}{\exception{ReferenceError}}{(2)}
+  \lineiii{PyExc_RuntimeError\ttindex{PyExc_RuntimeError}}{\exception{RuntimeError}}{}
+  \lineiii{PyExc_SyntaxError\ttindex{PyExc_SyntaxError}}{\exception{SyntaxError}}{}
+  \lineiii{PyExc_SystemError\ttindex{PyExc_SystemError}}{\exception{SystemError}}{}
+  \lineiii{PyExc_SystemExit\ttindex{PyExc_SystemExit}}{\exception{SystemExit}}{}
+  \lineiii{PyExc_TypeError\ttindex{PyExc_TypeError}}{\exception{TypeError}}{}
+  \lineiii{PyExc_ValueError\ttindex{PyExc_ValueError}}{\exception{ValueError}}{}
+  \lineiii{PyExc_WindowsError\ttindex{PyExc_WindowsError}}{\exception{WindowsError}}{(3)}
+  \lineiii{PyExc_ZeroDivisionError\ttindex{PyExc_ZeroDivisionError}}{\exception{ZeroDivisionError}}{}
+\end{tableiii}
+
+\noindent
+Notes:
+\begin{description}
+\item[(1)]
+  This is a base class for other standard exceptions.
+
+\item[(2)]
+  This is the same as \exception{weakref.ReferenceError}.
+
+\item[(3)]
+  Only defined on Windows; protect code that uses this by testing that
+  the preprocessor macro \code{MS_WINDOWS} is defined.
+
+\item[(4)]
+  \versionadded{2.5}
+\end{description}
+
+
+\section{Deprecation of String Exceptions}
+
+All exceptions built into Python or provided in the standard library
+are derived from \exception{BaseException}.
+\withsubitem{(built-in exception)}{\ttindex{BaseException}}
+
+String exceptions are still supported in the interpreter to allow
+existing code to run unmodified, but this will also change in a future
+release.