python-doc-tw
diff --git a/‎Doc/ACKS
+1 b/‎Doc/ACKS
+1
diff --git a/‎Doc/Makefile
+1-1 b/‎Doc/Makefile
+1-1
diff --git a/‎Doc/Makefile.deps
+1 b/‎Doc/Makefile.deps
+1
diff --git a/‎Doc/api/api.tex
-5 b/‎Doc/api/api.tex
-5
diff --git a/‎Doc/api/concrete.tex
+44-32 b/‎Doc/api/concrete.tex
+44-32
diff --git a/‎Doc/api/exceptions.tex
+16-2 b/‎Doc/api/exceptions.tex
+16-2
diff --git a/‎Doc/api/intro.tex
+56 b/‎Doc/api/intro.tex
+56
diff --git a/‎Doc/api/refcounts.dat
+5 b/‎Doc/api/refcounts.dat
+5
diff --git a/‎Doc/commontex/boilerplate.tex
+1-1 b/‎Doc/commontex/boilerplate.tex
+1-1
@@ -190,6 +190,7 @@ Eddy Welbourne
 Mats Wichmann
 Gerry Wiener
 Timothy Wild
+Collin Winter
 Blake Winton
 Dan Wolfe
 Steven Work
 
@@ -691,7 +691,7 @@ distlatex:	bziplatex ziplatex
 # The small amount of additional work is a small price to pay for not
 # having to remember which order to do it in. ;)
 paperdist:	distpdf distps pkglist
-edist:		disthtml distinfo zipisilo pkglist
+edist:		disthtml pkglist
 
 # The pkglist.html file is used as part of the download.html page on
 # python.org; it is not used as intermediate input here or as part of
 
@@ -270,6 +270,7 @@ LIBFILES= $(MANSTYLES) $(INDEXSTYLES) $(COMMONTEX) \
 	lib/xmlsaxhandler.tex \
 	lib/xmlsaxutils.tex \
 	lib/xmlsaxreader.tex \
+	lib/libetree.tex \
 	lib/libqueue.tex \
 	lib/liblocale.tex \
 	lib/libgettext.tex \
 
@@ -48,11 +48,6 @@ \chapter*{Front Matter\label{front}}
 \input{newtypes}
 
 
-% \chapter{Debugging \label{debugging}}
-%
-% XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
-
-
 \appendix
 \chapter{Reporting Bugs}
 \input{reportingbugs}
 
@@ -31,7 +31,7 @@ \subsection{Type Objects \label{typeObjects}}
 
 \begin{cvardesc}{PyObject*}{PyType_Type}
   This is the type object for type objects; it is the same object as
-  \code{types.TypeType} in the Python layer.
+  \code{type} and \code{types.TypeType} in the Python layer.
   \withsubitem{(in module types)}{\ttindex{TypeType}}
 \end{cvardesc}
 
@@ -117,7 +117,8 @@ \subsection{Plain Integer Objects \label{intObjects}}
 
 \begin{cvardesc}{PyTypeObject}{PyInt_Type}
   This instance of \ctype{PyTypeObject} represents the Python plain
-  integer type.  This is the same object as \code{types.IntType}.
+  integer type.  This is the same object as \code{int} and
+  \code{types.IntType}.
   \withsubitem{(in modules types)}{\ttindex{IntType}}
 \end{cvardesc}
 
@@ -260,7 +261,8 @@ \subsection{Long Integer Objects \label{longObjects}}
 
 \begin{cvardesc}{PyTypeObject}{PyLong_Type}
   This instance of \ctype{PyTypeObject} represents the Python long
-  integer type.  This is the same object as \code{types.LongType}.
+  integer type.  This is the same object as \code{long} and
+  \code{types.LongType}.
   \withsubitem{(in modules types)}{\ttindex{LongType}}
 \end{cvardesc}
 
@@ -376,7 +378,7 @@ \subsection{Long Integer Objects \label{longObjects}}
   \versionadded{2.3}
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLongLongMask}{PyObject *io}
+\begin{cfuncdesc}{unsigned PY_LONG_LONG}{PyLong_AsUnsignedLongLongMask}{PyObject *io}
   Return a C \ctype{unsigned long long} from a Python long integer, without
   checking for overflow.
   \versionadded{2.3}
@@ -411,7 +413,8 @@ \subsection{Floating Point Objects \label{floatObjects}}
 
 \begin{cvardesc}{PyTypeObject}{PyFloat_Type}
   This instance of \ctype{PyTypeObject} represents the Python floating
-  point type.  This is the same object as \code{types.FloatType}.
+  point type.  This is the same object as \code{float} and
+  \code{types.FloatType}.
   \withsubitem{(in modules types)}{\ttindex{FloatType}}
 \end{cvardesc}
 
@@ -520,7 +523,8 @@ \subsubsection{Complex Numbers as Python Objects}
 
 \begin{cvardesc}{PyTypeObject}{PyComplex_Type}
   This instance of \ctype{PyTypeObject} represents the Python complex
-  number type.
+  number type. It is the same object as \code{complex} and
+  \code{types.ComplexType}.
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
@@ -580,8 +584,8 @@ \subsection{String Objects \label{stringObjects}}
 
 \begin{cvardesc}{PyTypeObject}{PyString_Type}
   This instance of \ctype{PyTypeObject} represents the Python string
-  type; it is the same object as \code{types.TypeType} in the Python
-  layer.
+  type; it is the same object as \code{str} and \code{types.StringType}
+  in the Python layer.
   \withsubitem{(in module types)}{\ttindex{StringType}}.
 \end{cvardesc}
 
@@ -850,7 +854,8 @@ \subsection{Unicode Objects \label{unicodeObjects}}
 
 \begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
   This instance of \ctype{PyTypeObject} represents the Python Unicode
-  type.
+  type.  It is exposed to Python code as \code{unicode} and
+  \code{types.UnicodeType}.
 \end{cvardesc}
 
 The following APIs are really C macros and can be used to do fast
@@ -1001,21 +1006,14 @@ \subsection{Unicode Objects \label{unicodeObjects}}
                                                       const char *errors}
   Coerce an encoded object \var{obj} to an Unicode object and return a
   reference with incremented refcount.
+  
+  String and other char buffer compatible objects are decoded
+  according to the given encoding and using the error handling
+  defined by errors.  Both can be \NULL{} to have the interface
+  use the default values (see the next section for details).
 
-  Coercion is done in the following way:
-
-\begin{enumerate}
-\item  Unicode objects are passed back as-is with incremented
-       refcount. \note{These cannot be decoded; passing a non-\NULL{}
-       value for encoding will result in a \exception{TypeError}.}
-
-\item String and other char buffer compatible objects are decoded
-      according to the given encoding and using the error handling
-      defined by errors.  Both can be \NULL{} to have the interface
-      use the default values (see the next section for details).
-
-\item All other objects cause an exception.
-\end{enumerate}
+  All other objects, including Unicode objects, cause a
+  \exception{TypeError} to be set.
 
   The API returns \NULL{} if there was an error.  The caller is
   responsible for decref'ing the returned objects.
@@ -1431,6 +1429,18 @@ \subsubsection{Built-in Codecs \label{builtinCodecs}}
   raised by the codec.
 \end{cfuncdesc}
 
+\begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCSStateful}{const char *s,
+                                               int size,
+                                               const char *errors,
+                                               int *consumed}
+  If \var{consumed} is \NULL{}, behave like
+  \cfunction{PyUnicode_DecodeMBCS()}. If \var{consumed} is not \NULL{},
+  \cfunction{PyUnicode_DecodeMBCSStateful()} will not decode trailing lead
+  byte and the number of bytes that have been decoded will be stored in
+  \var{consumed}.
+  \versionadded{2.5}
+\end{cfuncdesc}
+
 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
                                                Py_ssize_t size,
                                                const char *errors}
@@ -1618,8 +1628,9 @@ \subsection{Buffer Objects \label{bufferObjects}}
 
 \begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
   The instance of \ctype{PyTypeObject} which represents the Python
-  buffer type; it is the same object as \code{types.BufferType} in the
-  Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}.
+  buffer type; it is the same object as \code{buffer} and 
+  \code{types.BufferType} in the Python layer.
+  \withsubitem{(in module types)}{\ttindex{BufferType}}.
 \end{cvardesc}
 
 \begin{cvardesc}{int}{Py_END_OF_BUFFER}
@@ -1693,8 +1704,8 @@ \subsection{Tuple Objects \label{tupleObjects}}
 
 \begin{cvardesc}{PyTypeObject}{PyTuple_Type}
   This instance of \ctype{PyTypeObject} represents the Python tuple
-  type; it is the same object as \code{types.TupleType} in the Python
-  layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
+  type; it is the same object as \code{tuple} and \code{types.TupleType}
+  in the Python layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
@@ -1790,8 +1801,8 @@ \subsection{List Objects \label{listObjects}}
 
 \begin{cvardesc}{PyTypeObject}{PyList_Type}
   This instance of \ctype{PyTypeObject} represents the Python list
-  type.  This is the same object as \code{types.ListType}.
-  \withsubitem{(in module types)}{\ttindex{ListType}}
+  type.  This is the same object as \code{list} and \code{types.ListType}
+  in the Python layer.\withsubitem{(in module types)}{\ttindex{ListType}}
 \end{cvardesc}
 
 \begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
@@ -1919,7 +1930,7 @@ \subsection{Dictionary Objects \label{dictObjects}}
 \begin{cvardesc}{PyTypeObject}{PyDict_Type}
   This instance of \ctype{PyTypeObject} represents the Python
   dictionary type.  This is exposed to Python programs as
-  \code{types.DictType} and \code{types.DictionaryType}.
+  \code{dict} and \code{types.DictType}.
   \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
 \end{cvardesc}
 
@@ -2134,7 +2145,8 @@ \subsection{File Objects \label{fileObjects}}
 
 \begin{cvardesc}{PyTypeObject}{PyFile_Type}
   This instance of \ctype{PyTypeObject} represents the Python file
-  type.  This is exposed to Python programs as \code{types.FileType}.
+  type.  This is exposed to Python programs as \code{file} and
+  \code{types.FileType}.
   \withsubitem{(in module types)}{\ttindex{FileType}}
 \end{cvardesc}
 
@@ -2583,7 +2595,7 @@ \subsection{Slice Objects \label{slice-objects}}
 
 \begin{cvardesc}{PyTypeObject}{PySlice_Type}
   The type object for slice objects.  This is the same as
-  \code{types.SliceType}.
+  \code{slice} and \code{types.SliceType}.
   \withsubitem{(in module types)}{\ttindex{SliceType}}
 \end{cvardesc}
 
 
@@ -256,10 +256,14 @@ \chapter{Exception Handling \label{exceptionHandling}}
   argument.  It is mostly for internal use.
 \end{cfuncdesc}
 
-\begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
+\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.
+  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
@@ -291,6 +295,16 @@ \chapter{Exception Handling \label{exceptionHandling}}
   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}
 
@@ -577,3 +577,59 @@ \section{Embedding Python \label{embedding}}
 Notice that \cfunction{Py_Finalize} does \emph{not} free all memory
 allocated by the Python interpreter, e.g. memory allocated by extension
 modules currently cannot be released.
+
+
+\section{Debugging Builds \label{debugging}}
+
+Python can be built with several macros to enable extra checks of the
+interpreter and extension modules.  These checks tend to add a large
+amount of overhead to the runtime so they are not enabled by default.
+
+A full list of the various types of debugging builds is in the file
+\file{Misc/SpecialBuilds.txt} in the Python source distribution.
+Builds are available that support tracing of reference counts,
+debugging the memory allocator, or low-level profiling of the main
+interpreter loop.  Only the most frequently-used builds will be
+described in the remainder of this section.
+
+Compiling the interpreter with the \csimplemacro{Py_DEBUG} macro
+defined produces what is generally meant by "a debug build" of Python.
+\csimplemacro{Py_DEBUG} is enabled in the \UNIX{} build by adding
+\longprogramopt{with-pydebug} to the \file{configure} command.  It is also
+implied by the presence of the not-Python-specific
+\csimplemacro{_DEBUG} macro.  When \csimplemacro{Py_DEBUG} is enabled
+in the \UNIX{} build, compiler optimization is disabled.
+
+In addition to the reference count debugging described below, the
+following extra checks are performed:
+
+\begin{itemize}
+      \item Extra checks are added to the object allocator.
+      \item Extra checks are added to the parser and compiler.
+      \item Downcasts from wide types to narrow types are checked for
+            loss of information.
+      \item A number of assertions are added to the dictionary and set
+            implementations.  In addition, the set object acquires a
+            \method{test_c_api} method.
+      \item Sanity checks of the input arguments are added to frame
+            creation. 
+      \item The storage for long ints is initialized with a known
+            invalid pattern to catch reference to uninitialized
+            digits. 
+      \item Low-level tracing and extra exception checking are added
+            to the runtime virtual machine.
+      \item Extra checks are added to the memory arena implementation.
+      \item Extra debugging is added to the thread module.
+\end{itemize}
+
+There may be additional checks not mentioned here.
+
+Defining \csimplemacro{Py_TRACE_REFS} enables reference tracing.  When
+defined, a circular doubly linked list of active objects is maintained
+by adding two extra fields to every \ctype{PyObject}.  Total
+allocations are tracked as well.  Upon exit, all existing references
+are printed.  (In interactive mode this happens after every statement
+run by the interpreter.)  Implied by \csimplemacro{Py_DEBUG}.
+
+Please refer to \file{Misc/SpecialBuilds.txt} in the Python source
+distribution for more detailed information.
@@ -303,6 +303,11 @@ PyErr_Warn:int:::
 PyErr_Warn:PyObject*:category:0:
 PyErr_Warn:char*:message::
 
+PyErr_WarnEx:int:::
+PyErr_WarnEx:PyObject*:category:0:
+PyErr_WarnEx:const char*:message::
+PyErr_WarnEx:Py_ssize_t:stack_level::
+
 PyEval_AcquireLock:void:::
 
 PyEval_AcquireThread:void:::
 
@@ -5,5 +5,5 @@
 	Email: \email{docs@python.org}
 }
 
-\date{\today}			% XXX update before final release!
+\date{3rd August, 2006}			% XXX update before final release!
 \input{patchlevel}		% include Python version information
Original file line number	Diff line number	Diff line change
`@@ -5,5 +5,5 @@`
`5`	`5`	`Email: \email{docs@python.org}`
`6`	`6`	`}`
`7`	`7`
`8`		`-\date{\today} % XXX update before final release!`
	`8`	`+\date{3rd August, 2006} % XXX update before final release!`
`9`	`9`	`\input{patchlevel} % include Python version information`