Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 555a24f

Browse files
author
Victor Stinner
committed
Issue #9738: Document encodings of error and warning functions
1 parent ab9d8d6 commit 555a24f

3 files changed

Lines changed: 78 additions & 24 deletions

File tree

‎Doc/c-api/exceptions.rst‎

Lines changed: 16 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -148,7 +148,8 @@ in various ways. There is a separate error indicator for each thread.
148148
This function sets the error indicator and returns *NULL*. *exception*
149149
should be a Python exception class. The *format* and subsequent
150150
parameters help format the error message; they have the same meaning and
151-
values as in :c:func:`PyUnicode_FromFormat`.
151+
values as in :c:func:`PyUnicode_FromFormat`. *format* is an ASCII-encoding
152+
string.
152153
153154
154155
.. c:function:: void PyErr_SetNone(PyObject *type)
@@ -218,7 +219,8 @@ in various ways. There is a separate error indicator for each thread.
218219
219220
Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that
220221
if *filename* is not *NULL*, it is passed to the constructor of
221-
:exc:`WindowsError` as a third parameter. Availability: Windows.
222+
:exc:`WindowsError` as a third parameter. *filename* is decoded from UTF-8.
223+
Availability: Windows.
222224
223225
224226
.. 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.
232234
Set file, line, and offset information for the current exception. If the
233235
current exception is not a :exc:`SyntaxError`, then it sets additional
234236
attributes, which make the exception printing subsystem think the exception
235-
is a :exc:`SyntaxError`.
237+
is a :exc:`SyntaxError`. *filename* is decoded from the filesystem encoding
238+
(:func:`sys.getfilesystemencoding`).
236239
237240
.. versionadded:: 3.2
238241
@@ -254,7 +257,7 @@ in various ways. There is a separate error indicator for each thread.
254257
.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stack_level)
255258
256259
Issue a warning message. The *category* argument is a warning category (see
257-
below) or *NULL*; the *message* argument is a message string. *stack_level* is a
260+
below) or *NULL*; the *message* argument is an UTF-8 encoded string. *stack_level* is a
258261
positive number giving a number of stack frames; the warning will be issued from
259262
the currently executing line of code in that stack frame. A *stack_level* of 1
260263
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.
294297
is a straightforward wrapper around the Python function
295298
:func:`warnings.warn_explicit`, see there for more information. The *module*
296299
and *registry* arguments may be set to *NULL* to get the default effect
297-
described there.
300+
described there. *message*, *filename* and *module* are UTF-8 encoded
301+
strings.
298302
299303
300304
.. c:function:: int PyErr_WarnFormat(PyObject *category, Py_ssize_t stack_level, const char *format, ...)
301305
302306
Function similar to :c:func:`PyErr_WarnEx`, but use
303-
:c:func:`PyUnicode_FromFormat` to format the warning message.
307+
:c:func:`PyUnicode_FromFormat` to format the warning message. *format* is
308+
an ASCII-encoded string.
304309
305310
.. versionadded:: 3.2
306311
@@ -437,17 +442,19 @@ The following functions are used to create and modify Unicode exceptions from C.
437442
.. 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)
438443
439444
Create a :class:`UnicodeDecodeError` object with the attributes *encoding*,
440-
*object*, *length*, *start*, *end* and *reason*.
445+
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
446+
UTF-8 encoded strings.
441447
442448
.. 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)
443449
444450
Create a :class:`UnicodeEncodeError` object with the attributes *encoding*,
445-
*object*, *length*, *start*, *end* and *reason*.
451+
*object*, *length*, *start*, *end* and *reason*. *encoding* and *reason* are
452+
UTF-8 encoded strings.
446453
447454
.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason)
448455
449456
Create a :class:`UnicodeTranslateError` object with the attributes *object*,
450-
*length*, *start*, *end* and *reason*.
457+
*length*, *start*, *end* and *reason*. *reason* is an UTF-8 encoded string.
451458
452459
.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc)
453460
PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc)

‎Include/pyerrors.h‎

Lines changed: 46 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -201,7 +201,9 @@ PyAPI_FUNC(PyObject *) PyErr_Format(
201201
PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithFilenameObject(
202202
int, const char *);
203203
PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithFilename(
204-
int, const char *);
204+
int ierr,
205+
const char *filename /* decoded from UTF-8 */
206+
);
205207
#ifndef Py_LIMITED_API
206208
/* XXX redeclare to use WSTRING */
207209
PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErrWithUnicodeFilename(
@@ -211,7 +213,10 @@ PyAPI_FUNC(PyObject *) PyErr_SetFromWindowsErr(int);
211213
PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilenameObject(
212214
PyObject *,int, PyObject *);
213215
PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithFilename(
214-
PyObject *,int, const char *);
216+
PyObject *exc,
217+
int ierr,
218+
const char *filename /* decoded from UTF-8 */
219+
);
215220
#ifndef Py_LIMITED_API
216221
PyAPI_FUNC(PyObject *) PyErr_SetExcFromWindowsErrWithUnicodeFilename(
217222
PyObject *,int, const Py_UNICODE *);
@@ -243,27 +248,51 @@ int PySignal_SetWakeupFd(int fd);
243248
#endif
244249

245250
/* Support for adding program text to SyntaxErrors */
246-
PyAPI_FUNC(void) PyErr_SyntaxLocation(const char *, int);
247-
PyAPI_FUNC(void) PyErr_SyntaxLocationEx(const char *, int, int);
248-
PyAPI_FUNC(PyObject *) PyErr_ProgramText(const char *, int);
251+
PyAPI_FUNC(void) PyErr_SyntaxLocation(
252+
const char *filename, /* decoded from the filesystem encoding */
253+
int lineno);
254+
PyAPI_FUNC(void) PyErr_SyntaxLocationEx(
255+
const char *filename, /* decoded from the filesystem encoding */
256+
int lineno,
257+
int col_offset);
258+
PyAPI_FUNC(PyObject *) PyErr_ProgramText(
259+
const char *filename, /* decoded from the filesystem encoding */
260+
int lineno);
249261

250262
/* The following functions are used to create and modify unicode
251263
exceptions from C */
252264

253265
/* create a UnicodeDecodeError object */
254266
PyAPI_FUNC(PyObject *) PyUnicodeDecodeError_Create(
255-
const char *, const char *, Py_ssize_t, Py_ssize_t, Py_ssize_t, const char *);
267+
const char *encoding, /* UTF-8 encoded string */
268+
const char *object,
269+
Py_ssize_t length,
270+
Py_ssize_t start,
271+
Py_ssize_t end,
272+
const char *reason /* UTF-8 encoded string */
273+
);
256274

257275
/* create a UnicodeEncodeError object */
258276
#ifndef Py_LIMITED_API
259277
PyAPI_FUNC(PyObject *) PyUnicodeEncodeError_Create(
260-
const char *, const Py_UNICODE *, Py_ssize_t, Py_ssize_t, Py_ssize_t, const char *);
278+
const char *encoding, /* UTF-8 encoded string */
279+
const Py_UNICODE *object,
280+
Py_ssize_t length,
281+
Py_ssize_t start,
282+
Py_ssize_t end,
283+
const char *reason /* UTF-8 encoded string */
284+
);
261285
#endif
262286

263287
/* create a UnicodeTranslateError object */
264288
#ifndef Py_LIMITED_API
265289
PyAPI_FUNC(PyObject *) PyUnicodeTranslateError_Create(
266-
const Py_UNICODE *, Py_ssize_t, Py_ssize_t, Py_ssize_t, const char *);
290+
const Py_UNICODE *object,
291+
Py_ssize_t length,
292+
Py_ssize_t start,
293+
Py_ssize_t end,
294+
const char *reason /* UTF-8 encoded string */
295+
);
267296
#endif
268297

269298
/* get the encoding attribute */
@@ -307,11 +336,17 @@ PyAPI_FUNC(PyObject *) PyUnicodeTranslateError_GetReason(PyObject *);
307336
/* assign a new value to the reason attribute
308337
return 0 on success, -1 on failure */
309338
PyAPI_FUNC(int) PyUnicodeEncodeError_SetReason(
310-
PyObject *, const char *);
339+
PyObject *exc,
340+
const char *reason /* UTF-8 encoded string */
341+
);
311342
PyAPI_FUNC(int) PyUnicodeDecodeError_SetReason(
312-
PyObject *, const char *);
343+
PyObject *exc,
344+
const char *reason /* UTF-8 encoded string */
345+
);
313346
PyAPI_FUNC(int) PyUnicodeTranslateError_SetReason(
314-
PyObject *, const char *);
347+
PyObject *exc,
348+
const char *reason /* UTF-8 encoded string */
349+
);
315350

316351

317352
/* These APIs aren't really part of the error implementation, but

‎Include/warnings.h‎

Lines changed: 16 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,22 @@ extern "C" {
88
PyAPI_FUNC(PyObject*) _PyWarnings_Init(void);
99
#endif
1010

11-
PyAPI_FUNC(int) PyErr_WarnEx(PyObject *, const char *, Py_ssize_t);
12-
PyAPI_FUNC(int) PyErr_WarnFormat(PyObject *, Py_ssize_t, const char *, ...);
13-
PyAPI_FUNC(int) PyErr_WarnExplicit(PyObject *, const char *, const char *, int,
14-
const char *, PyObject *);
11+
PyAPI_FUNC(int) PyErr_WarnEx(
12+
PyObject *category,
13+
const char *message, /* UTF-8 encoded string */
14+
Py_ssize_t stack_level);
15+
PyAPI_FUNC(int) PyErr_WarnFormat(
16+
PyObject *category,
17+
Py_ssize_t stack_level,
18+
const char *format, /* ASCII-encoded string */
19+
...);
20+
PyAPI_FUNC(int) PyErr_WarnExplicit(
21+
PyObject *category,
22+
const char *message, /* UTF-8 encoded string */
23+
const char *filename, /* UTF-8 encoded string */
24+
int lineno,
25+
const char *module, /* UTF-8 encoded string */
26+
PyObject *registry);
1527

1628
/* DEPRECATED: Use PyErr_WarnEx() instead. */
1729
#ifndef Py_LIMITED_API

0 commit comments

Comments
 (0)