traverseda
/
cpython
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

Issue #9738: Document encodings of error and warning functions

This commit is contained in:
Victor Stinner 2010-12-27 01:49:26 +00:00
parent ab9d8d64a7
commit 555a24f206
3 changed files with 78 additions and 24 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

25
Doc/c-api/exceptions.rst
View File

@ -148,7 +148,8 @@ in various ways. There is a separate error indicator for each thread.
This function sets the error indicator and returns *NULL*. *exception*
should be a Python exception class. The *format* and subsequent
parameters help format the error message; they have the same meaning and
values as in :c:func:`PyUnicode_FromFormat`.
values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoding
string.
.. c:function:: void PyErr_SetNone(PyObject *type)
@ -218,7 +219,8 @@ in various ways. There is a separate error indicator for each thread.
Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that
if *filename* is not *NULL*, it is passed to the constructor of
:exc:`WindowsError` as a third parameter. Availability: Windows.
:exc:`WindowsError` as a third parameter. *filename* is decoded from UTF-8.
Availability: Windows.
.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
@ -232,7 +234,8 @@ in various ways. There is a separate error indicator for each thread.
Set file, line, and offset information for the current exception. If the
current exception is not a :exc:`SyntaxError`, then it sets additional
attributes, which make the exception printing subsystem think the exception
is a :exc:`SyntaxError`.
is a :exc:`SyntaxError`. *filename* is decoded from the filesystem encoding
(:func:`sys.getfilesystemencoding`).
.. versionadded:: 3.2
@ -254,7 +257,7 @@ in various ways. There is a separate error indicator for each thread.
.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stack_level)
Issue a warning message. The *category* argument is a warning category (see
below) or *NULL*; the *message* argument is a message string. *stack_level* is a
below) or *NULL*; the *message* argument is an UTF-8 encoded string. *stack_level* 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 *stack_level* of 1
is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that,
@ -294,13 +297,15 @@ in various ways. There is a separate error indicator for each thread.
is a straightforward wrapper around the Python function
:func:`warnings.warn_explicit`, see there for more information. The *module*
and *registry* arguments may be set to *NULL* to get the default effect
described there.
described there. *message*, *filename* and *module* are UTF-8 encoded
strings.
.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
Function similar to :c:func:`PyErr_WarnEx`, but use
:c:func:`PyUnicode_FromFormat` to format the warning message.
:c:func:`PyUnicode_FromFormat` to format the warning message. *format* is
an ASCII-encoded string.
.. versionadded:: 3.2
@ -437,17 +442,19 @@ The following functions are used to create and modify Unicode exceptions from C.
.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
*object*, *length*, *start*, *end* and *reason*.
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
UTF-8 encoded strings.
.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
*object*, *length*, *start*, *end* and *reason*.
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
UTF-8 encoded strings.
.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
*length*, *start*, *end* and *reason*.
*length*, *start*, *end* and *reason*. *reason* is an UTF-8 encoded string.
.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)

57
Include/pyerrors.h
View File

@ -201,7 +201,9 @@ PyAPI_FUNC(PyObject *) PyErr_Format(
PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithFilenameObject(
int, const char *);
PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithFilename(
int, const char *);
int ierr,
const char *filename /* decoded from UTF-8 */
);
#ifndef Py_LIMITED_API
/* XXX redeclare to use WSTRING */
PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithUnicodeFilename(
@ -211,7 +213,10 @@ PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErr(int);
PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilenameObject(
PyObject *,int, PyObject *);
PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilename(
PyObject *,int, const char *);
PyObject *exc,
int ierr,
const char *filename /* decoded from UTF-8 */
);
#ifndef Py_LIMITED_API
PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithUnicodeFilename(
PyObject *,int, const Py_UNICODE *);
@ -243,27 +248,51 @@ int PySignal_SetWakeupFd(int fd);
#endif
/* Support for adding program text to SyntaxErrors */
PyAPI_FUNC(void) PyErr_SyntaxLocation(const char *, int);
PyAPI_FUNC(void) PyErr_SyntaxLocationEx(const char *, int, int);
PyAPI_FUNC(PyObject *) PyErr_ProgramText(const char *, int);
PyAPI_FUNC(void) PyErr_SyntaxLocation(
const char *filename, /* decoded from the filesystem encoding */
int lineno);
PyAPI_FUNC(void) PyErr_SyntaxLocationEx(
const char *filename, /* decoded from the filesystem encoding */
int lineno,
int col_offset);
PyAPI_FUNC(PyObject *) PyErr_ProgramText(
const char *filename, /* decoded from the filesystem encoding */
int lineno);
/* The following functions are used to create and modify unicode
exceptions from C */
/* create a UnicodeDecodeError object */
PyAPI_FUNC(PyObject *) PyUnicodeDecodeError_Create(
const char *, const char *, Py_ssize_t, Py_ssize_t, Py_ssize_t, const char *);
const char *encoding, /* UTF-8 encoded string */
const char *object,
Py_ssize_t length,
Py_ssize_t start,
Py_ssize_t end,
const char *reason /* UTF-8 encoded string */
);
/* create a UnicodeEncodeError object */
#ifndef Py_LIMITED_API
PyAPI_FUNC(PyObject *) PyUnicodeEncodeError_Create(
const char *, const Py_UNICODE *, Py_ssize_t, Py_ssize_t, Py_ssize_t, const char *);
const char *encoding, /* UTF-8 encoded string */
const Py_UNICODE *object,
Py_ssize_t length,
Py_ssize_t start,
Py_ssize_t end,
const char *reason /* UTF-8 encoded string */
);
#endif
/* create a UnicodeTranslateError object */
#ifndef Py_LIMITED_API
PyAPI_FUNC(PyObject *) PyUnicodeTranslateError_Create(
const Py_UNICODE *, Py_ssize_t, Py_ssize_t, Py_ssize_t, const char *);
const Py_UNICODE *object,
Py_ssize_t length,
Py_ssize_t start,
Py_ssize_t end,
const char *reason /* UTF-8 encoded string */
);
#endif
/* get the encoding attribute */
@ -307,11 +336,17 @@ PyAPI_FUNC(PyObject *) PyUnicodeTranslateError_GetReason(PyObject *);
/* assign a new value to the reason attribute
return 0 on success, -1 on failure */
PyAPI_FUNC(int) PyUnicodeEncodeError_SetReason(
PyObject *, const char *);
PyObject *exc,
const char *reason /* UTF-8 encoded string */
);
PyAPI_FUNC(int) PyUnicodeDecodeError_SetReason(
PyObject *, const char *);
PyObject *exc,
const char *reason /* UTF-8 encoded string */
);
PyAPI_FUNC(int) PyUnicodeTranslateError_SetReason(
PyObject *, const char *);
PyObject *exc,
const char *reason /* UTF-8 encoded string */
);
/* These APIs aren't really part of the error implementation, but

20
Include/warnings.h
View File

@ -8,10 +8,22 @@ extern "C" {
PyAPI_FUNC(PyObject*) _PyWarnings_Init(void);
#endif
PyAPI_FUNC(int) PyErr_WarnEx(PyObject *, const char *, Py_ssize_t);
PyAPI_FUNC(int) PyErr_WarnFormat(PyObject *, Py_ssize_t, const char *, ...);
PyAPI_FUNC(int) PyErr_WarnExplicit(PyObject *, const char *, const char *, int,
const char *, PyObject *);
PyAPI_FUNC(int) PyErr_WarnEx(
PyObject *category,
const char *message, /* UTF-8 encoded string */
Py_ssize_t stack_level);
PyAPI_FUNC(int) PyErr_WarnFormat(
PyObject *category,
Py_ssize_t stack_level,
const char *format, /* ASCII-encoded string */
...);
PyAPI_FUNC(int) PyErr_WarnExplicit(
PyObject *category,
const char *message, /* UTF-8 encoded string */
const char *filename, /* UTF-8 encoded string */
int lineno,
const char *module, /* UTF-8 encoded string */
PyObject *registry);
/* DEPRECATED: Use PyErr_WarnEx() instead. */
#ifndef Py_LIMITED_API