diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst index e7805ba143c584..3ada0ba12e2f1d 100644 --- a/Doc/c-api/exceptions.rst +++ b/Doc/c-api/exceptions.rst @@ -1,37 +1,45 @@ .. highlight:: c +.. _exceptions: + +For this document the term ``exception`` refers to a condition that requires +special processing. The functions described in this chapter describe both how to +respond to an exception and how to raise Python exceptions. + +// Understanding the basics of Python is important for exception handling. + .. _exceptionhandling: ****************** Exception Handling ****************** -The functions described in this chapter will let you handle and raise Python -exceptions. It is important to understand some of the basics of Python -exception handling. It works somewhat like the POSIX :c:data:`errno` variable: -there is a global indicator (per thread) of the last error that occurred. Most -C API functions don't clear this on success, but will set it to indicate the -cause of the error on failure. Most C API functions also return an error -indicator, usually ``NULL`` if they are supposed to return a pointer, or ``-1`` -if they return an integer (exception: the :c:func:`PyArg_\*` functions -return ``1`` for success and ``0`` for failure). - -Concretely, the error indicator consists of three object pointers: the +Exception handling in Python is similiar to handling the POSIX :c:data:`errno` +variable. ``Errno`` is a global indicator (per thread) of the last error that +occurred. Most C API functions don't clear this on success, but will set +``errno`` to indicate the cause of the error on failure. Most C API functions +also return an error indicator.. This is normally ``NULL`` when they are +supposed to return a pointer, or ``-1`` when they return an integer. Notice +the difference with Python exceptions (or errors): +the :c:func:`PyArg_\*` functions return ``1`` for success and ``0`` for failure. + +In Python, the error indicator consists of three object pointers: the exception's type, the exception's value, and the traceback object. Any of those pointers can be ``NULL`` if non-set (although some combinations are forbidden, for example you can't have a non-``NULL`` traceback if the exception type is ``NULL``). -When a function must fail because some function it called failed, it generally -doesn't set the error indicator; the function it called already set it. It is -responsible for either handling the error and clearing the exception or -returning after cleaning up any resources it holds (such as object references or -memory allocations); it should *not* continue normally if it is not prepared to -handle the error. If returning due to an error, it is important to indicate to -the caller that an error has been set. If the error is not handled or carefully -propagated, additional calls into the Python/C API may not behave as intended -and may fail in mysterious ways. +When a function fails because some function it called has already failed, it +generally doesn't set the error indicator again because the function it called +has already set ``errno``. Instead the function is now responsible for either +a) handling the error and clearing the exception or b) returning after cleaning +up any resources it holds (such as object references or memory allocations). +The function should *not* continue normally when it is not prepared to +handle the error. When a function returns due to an error, it is important +to indicate to the caller that an error has been set. If the error is not +handled or carefully propagated, additional calls into the Python/C API may +not behave as intended and fail in mysterious ways. .. note:: The error indicator is **not** the result of :func:`sys.exc_info()`. @@ -77,7 +85,7 @@ Printing and clearing This utility function prints a warning message to ``sys.stderr`` when an exception has been set but it is impossible for the interpreter to actually - raise the exception. It is used, for example, when an exception occurs in an + raise the exception. This is used, for example, when an exception occurs in an :meth:`__del__` method. The function is called with a single argument *obj* that identifies the context @@ -99,13 +107,14 @@ For convenience, some of these functions will always return a This is the most common way to set the error indicator. The first argument specifies the exception type; it is normally one of the standard exceptions, - e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count. - The second argument is an error message; it is decoded from ``'utf-8``'. + e.g. :c:data:`PyExc_RuntimeError`. This function does not affect the object's + reference count. The second argument is an error message; it is decoded + from ``'utf-8``'. .. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value) - This function is similar to :c:func:`PyErr_SetString` but lets you specify an + This function is similar to :c:func:`PyErr_SetString` but accepts an arbitrary Python object for the "value" of the exception. @@ -135,7 +144,7 @@ For convenience, some of these functions will always return a This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where *message* indicates that a built-in operation was invoked with an illegal - argument. It is mostly for internal use. + argument. This call is for internal use. .. c:function:: PyObject* PyErr_NoMemory() @@ -368,10 +377,11 @@ Querying the error indicator .. c:function:: PyObject* PyErr_Occurred() - Test whether the error indicator is set. If set, return the exception *type* - (the first argument to the last call to one of the :c:func:`PyErr_Set\*` - functions or to :c:func:`PyErr_Restore`). If not set, return ``NULL``. You do not - own a reference to the return value, so you do not need to :c:func:`Py_DECREF` + Test whether the error indicator is set. When an error indicator set this + call returns the exception *type* (the first argument to the last call to one + of the :c:func:`PyErr_Set\*` functions or to :c:func:`PyErr_Restore`). When + no error indicator is set this call returns ``NULL``. The caller does not + own a reference to the return value so there is no need to :c:func:`Py_DECREF` it. The caller must hold the GIL. @@ -402,9 +412,10 @@ Querying the error indicator .. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) Retrieve the error indicator into three variables whose addresses are passed. - If the error indicator is not set, set all three variables to ``NULL``. If it is - set, it will be cleared and you own a reference to each object retrieved. The - value and traceback object may be ``NULL`` even when the type object is not. + If the error indicator is not set, set all three variables to ``NULL``. If the + error indicator is set, it will be cleared and you own a reference to each object + retrieved. The value and traceback object may be ``NULL`` even when the type + object is not. .. note:: @@ -423,15 +434,15 @@ Querying the error indicator .. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback) - Set the error indicator from the three objects. If the error indicator is + Set the error indicator from the three objects. If the error indicator is already set, it is cleared first. If the objects are ``NULL``, the error indicator is cleared. Do not pass a ``NULL`` type and non-``NULL`` value or traceback. The exception type should be a class. Do not pass an invalid exception type or value. (Violating these rules will cause subtle problems later.) This call takes away a reference to each object: you must own a reference to each object before the call and after the call you no longer own - these references. (If you don't understand this, don't use this function. I - warned you.) + these references. (If you don't understand this, don't use this function. + You have been warned.) .. note:: diff --git a/Misc/NEWS.d/next/Documentation/2020-07-27-12-57-05.bpo-18280.d3mI4n.rst b/Misc/NEWS.d/next/Documentation/2020-07-27-12-57-05.bpo-18280.d3mI4n.rst new file mode 100644 index 00000000000000..3c27fe5c39449d --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2020-07-27-12-57-05.bpo-18280.d3mI4n.rst @@ -0,0 +1,6 @@ +Make documentation less personal. + +Rather than personal pronouns (I, you, we) re-write documentation without +personal reference when possible - using 3rd person in other cases. + +Patch by M. Felt. pFad - Phonifier reborn

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.


Alternative Proxies:

Alternative Proxy

pFad Proxy

pFad v3 Proxy

pFad v4 Proxy