From 555a24f206e4d310feb55ddb03cb7eba12d901e7 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Mon, 27 Dec 2010 01:49:26 +0000 Subject: Issue #9738: Document encodings of error and warning functions --- Doc/c-api/exceptions.rst | 25 +++++++++++++-------- Include/pyerrors.h | 57 ++++++++++++++++++++++++++++++++++++++---------- Include/warnings.h | 20 +++++++++++++---- 3 files changed, 78 insertions(+), 24 deletions(-) diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index c09b4cf..9fec46f 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -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) diff --git a/Include/pyerrors.h b/Include/pyerrors.h index d72ce07..05c5ea8 100644 --- a/Include/pyerrors.h +++ b/Include/pyerrors.h @@ -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 diff --git a/Include/warnings.h b/Include/warnings.h index 82abb11..7553a25 100644 --- a/Include/warnings.h +++ b/Include/warnings.h @@ -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 -- cgit v0.12