add hg and python

1 files changed, 157 insertions, 0 deletions

diff --git a/sys/src/cmd/python/Doc/lib/libtraceback.tex b/sys/src/cmd/python/Doc/lib/libtraceback.tex
new file mode 100644
index 000000000..b7f61ace9
--- /dev/null
+++ b/sys/src/cmd/python/Doc/lib/libtraceback.tex
@@ -0,0 +1,157 @@
+\section{\module{traceback} ---
+         Print or retrieve a stack traceback}
+
+\declaremodule{standard}{traceback}
+\modulesynopsis{Print or retrieve a stack traceback.}
+
+
+This module provides a standard interface to extract, format and print
+stack traces of Python programs.  It exactly mimics the behavior of
+the Python interpreter when it prints a stack trace.  This is useful
+when you want to print stack traces under program control, such as in a
+``wrapper'' around the interpreter.
+
+The module uses traceback objects --- this is the object type that is
+stored in the variables \code{sys.exc_traceback} (deprecated) and
+\code{sys.last_traceback} and returned as the third item from
+\function{sys.exc_info()}.
+\obindex{traceback}
+
+The module defines the following functions:
+
+\begin{funcdesc}{print_tb}{traceback\optional{, limit\optional{, file}}}
+Print up to \var{limit} stack trace entries from \var{traceback}.  If
+\var{limit} is omitted or \code{None}, all entries are printed.
+If \var{file} is omitted or \code{None}, the output goes to
+\code{sys.stderr}; otherwise it should be an open file or file-like
+object to receive the output.
+\end{funcdesc}
+
+\begin{funcdesc}{print_exception}{type, value, traceback\optional{,
+                                  limit\optional{, file}}}
+Print exception information and up to \var{limit} stack trace entries
+from \var{traceback} to \var{file}.
+This differs from \function{print_tb()} in the
+following ways: (1) if \var{traceback} is not \code{None}, it prints a
+header \samp{Traceback (most recent call last):}; (2) it prints the
+exception \var{type} and \var{value} after the stack trace; (3) if
+\var{type} is \exception{SyntaxError} and \var{value} has the
+appropriate format, it prints the line where the syntax error occurred
+with a caret indicating the approximate position of the error.
+\end{funcdesc}
+
+\begin{funcdesc}{print_exc}{\optional{limit\optional{, file}}}
+This is a shorthand for \code{print_exception(sys.exc_type,
+sys.exc_value, sys.exc_traceback, \var{limit}, \var{file})}.  (In
+fact, it uses \function{sys.exc_info()} to retrieve the same
+information in a thread-safe way instead of using the deprecated
+variables.)
+\end{funcdesc}
+
+\begin{funcdesc}{format_exc}{\optional{limit}}
+This is like \code{print_exc(\var{limit})} but returns a string
+instead of printing to a file.
+\versionadded{2.4}
+\end{funcdesc}
+
+\begin{funcdesc}{print_last}{\optional{limit\optional{, file}}}
+This is a shorthand for \code{print_exception(sys.last_type,
+sys.last_value, sys.last_traceback, \var{limit}, \var{file})}.
+\end{funcdesc}
+
+\begin{funcdesc}{print_stack}{\optional{f\optional{, limit\optional{, file}}}}
+This function prints a stack trace from its invocation point.  The
+optional \var{f} argument can be used to specify an alternate stack
+frame to start.  The optional \var{limit} and \var{file} arguments have the
+same meaning as for \function{print_exception()}.
+\end{funcdesc}
+
+\begin{funcdesc}{extract_tb}{traceback\optional{, limit}}
+Return a list of up to \var{limit} ``pre-processed'' stack trace
+entries extracted from the traceback object \var{traceback}.  It is
+useful for alternate formatting of stack traces.  If \var{limit} is
+omitted or \code{None}, all entries are extracted.  A
+``pre-processed'' stack trace entry is a quadruple (\var{filename},
+\var{line number}, \var{function name}, \var{text}) representing
+the information that is usually printed for a stack trace.  The
+\var{text} is a string with leading and trailing whitespace
+stripped; if the source is not available it is \code{None}.
+\end{funcdesc}
+
+\begin{funcdesc}{extract_stack}{\optional{f\optional{, limit}}}
+Extract the raw traceback from the current stack frame.  The return
+value has the same format as for \function{extract_tb()}.  The
+optional \var{f} and \var{limit} arguments have the same meaning as
+for \function{print_stack()}.
+\end{funcdesc}
+
+\begin{funcdesc}{format_list}{list}
+Given a list of tuples as returned by \function{extract_tb()} or
+\function{extract_stack()}, return a list of strings ready for
+printing.  Each string in the resulting list corresponds to the item
+with the same index in the argument list.  Each string ends in a
+newline; the strings may contain internal newlines as well, for those
+items whose source text line is not \code{None}.
+\end{funcdesc}
+
+\begin{funcdesc}{format_exception_only}{type, value}
+Format the exception part of a traceback.  The arguments are the
+exception type and value such as given by \code{sys.last_type} and
+\code{sys.last_value}.  The return value is a list of strings, each
+ending in a newline.  Normally, the list contains a single string;
+however, for \exception{SyntaxError} exceptions, it contains several
+lines that (when printed) display detailed information about where the
+syntax error occurred.  The message indicating which exception
+occurred is the always last string in the list.
+\end{funcdesc}
+
+\begin{funcdesc}{format_exception}{type, value, tb\optional{, limit}}
+Format a stack trace and the exception information.  The arguments 
+have the same meaning as the corresponding arguments to
+\function{print_exception()}.  The return value is a list of strings,
+each ending in a newline and some containing internal newlines.  When
+these lines are concatenated and printed, exactly the same text is
+printed as does \function{print_exception()}.
+\end{funcdesc}
+
+\begin{funcdesc}{format_tb}{tb\optional{, limit}}
+A shorthand for \code{format_list(extract_tb(\var{tb}, \var{limit}))}.
+\end{funcdesc}
+
+\begin{funcdesc}{format_stack}{\optional{f\optional{, limit}}}
+A shorthand for \code{format_list(extract_stack(\var{f}, \var{limit}))}.
+\end{funcdesc}
+
+\begin{funcdesc}{tb_lineno}{tb}
+This function returns the current line number set in the traceback
+object.  This function was necessary because in versions of Python
+prior to 2.3 when the \programopt{-O} flag was passed to Python the
+\code{\var{tb}.tb_lineno} was not updated correctly.  This function
+has no use in versions past 2.3.
+\end{funcdesc}
+
+
+\subsection{Traceback Example \label{traceback-example}}
+
+This simple example implements a basic read-eval-print loop, similar
+to (but less useful than) the standard Python interactive interpreter
+loop.  For a more complete implementation of the interpreter loop,
+refer to the \refmodule{code} module.
+
+\begin{verbatim}
+import sys, traceback
+
+def run_user_code(envdir):
+    source = raw_input(">>> ")
+    try:
+        exec source in envdir
+    except:
+        print "Exception in user code:"
+        print '-'*60
+        traceback.print_exc(file=sys.stdout)
+        print '-'*60
+
+envdir = {}
+while 1:
+    run_user_code(envdir)
+\end{verbatim}