diff options
Diffstat (limited to 'Doc/c-api/intro.rst')
| -rw-r--r-- | Doc/c-api/intro.rst | 62 |
1 files changed, 57 insertions, 5 deletions
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 @@ common use. The second reason is to use Python as a component in a larger 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 @@ familiar with writing an extension before attempting to embed Python in a real 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 @@ header files do properly declare the entry points to be ``extern "C"``, so there 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 |