From 69a57b0cffeb5de46dfa03f01bd13c0ed37cf54e Mon Sep 17 00:00:00 2001 From: M Felt aka aixtools Date: Mon, 27 Jul 2020 13:01:58 +0000 Subject: [PATCH] Make documentation less personal. --- Doc/c-api/exceptions.rst | 81 +++++++++++-------- .../2020-07-27-12-57-05.bpo-18280.d3mI4n.rst | 6 ++ 2 files changed, 52 insertions(+), 35 deletions(-) create mode 100644 Misc/NEWS.d/next/Documentation/2020-07-27-12-57-05.bpo-18280.d3mI4n.rst 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.