[Python-checkins] r51000 - python/trunk/Doc/api/exceptions.tex

[andrew.kuchling]

Author: andrew.kuchling
Date: Mon Jul 31 14:39:05 2006
New Revision: 51000

Modified:
   python/trunk/Doc/api/exceptions.tex
Log:
Document PyErr_WarnEx.  (Bad Neal!  No biscuit!)

Is the explanation of the 'stacklevel' parameter clear?  Please feel free
to edit it.

I don't have LaTeX installed on this machine, so haven't verified that the
markup is correct.  Will check tonight, or maybe the automatic doc build will
tell me.


Modified: python/trunk/Doc/api/exceptions.tex
==============================================================================
--- python/trunk/Doc/api/exceptions.tex	(original)
+++ python/trunk/Doc/api/exceptions.tex	Mon Jul 31 14:39:05 2006
@@ -259,10 +259,14 @@
   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
@@ -294,6 +298,16 @@
   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_Warn()} 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}