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}