bpo-31338 (#3374)
* Add Py_UNREACHABLE() as an alias to abort().
* Use Py_UNREACHABLE() instead of assert(0)
* Convert more unreachable code to use Py_UNREACHABLE()
* Document Py_UNREACHABLE() and a few other macros.
diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst
index 74681d2..4942b1a 100644
--- a/Doc/c-api/intro.rst
+++ b/Doc/c-api/intro.rst
@@ -17,11 +17,11 @@
application; this technique is generally referred to as :dfn:`embedding` Python
in an application.
-Writing an extension module is a relatively well-understood process, where a
-"cookbook" approach works well. There are several tools that automate the
-process to some extent. While people have embedded Python in other
-applications since its early existence, the process of embedding Python is less
-straightforward than writing an extension.
+Writing an extension module is a relatively well-understood process, where a
+"cookbook" approach works well. There are several tools that automate the
+process to some extent. While people have embedded Python in other
+applications since its early existence, the process of embedding Python is
+less straightforward than writing an extension.
Many API functions are useful independent of whether you're embedding or
extending Python; moreover, most applications that embed Python will need to
@@ -30,6 +30,16 @@
application.
+Coding standards
+================
+
+If you're writing C code for inclusion in CPython, you **must** follow the
+guidelines and standards defined in :PEP:`7`. These guidelines apply
+regardless of the version of Python you are contributing to. Following these
+conventions is not necessary for your own third party extension modules,
+unless you eventually expect to contribute them to Python.
+
+
.. _api-includes:
Include Files
@@ -81,6 +91,48 @@
is no need to do anything special to use the API from C++.
+Useful macros
+=============
+
+Several useful macros are defined in the Python header files. Many are
+defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
+Others of a more general utility are defined here. This is not necessarily a
+complete listing.
+
+.. c:macro:: Py_UNREACHABLE()
+
+ Use this when you have a code path that you do not expect to be reached.
+ For example, in the ``default:`` clause in a ``switch`` statement for which
+ all possible values are covered in ``case`` statements. Use this in places
+ where you might be tempted to put an ``assert(0)`` or ``abort()`` call.
+
+.. c:macro:: Py_ABS(x)
+
+ Return the absolute value of ``x``.
+
+.. c:macro:: Py_MIN(x, y)
+
+ Return the minimum value between ``x`` and ``y``.
+
+.. c:macro:: Py_MAX(x, y)
+
+ Return the maximum value between ``x`` and ``y``.
+
+.. c:macro:: Py_STRINGIFY(x)
+
+ Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
+ ``"123"``.
+
+.. c:macro:: Py_MEMBER_SIZE(type, member)
+
+ Return the size of a structure (``type``) ``member`` in bytes.
+
+.. c:macro:: Py_CHARMASK(c)
+
+ Argument must be a character or an integer in the range [-128, 127] or [0,
+ 255]. This macro returns ``c`` cast to an ``unsigned char``.
+
+
.. _api-objects:
Objects, Types and Reference Counts