bpo-31338 (#3374) · python/cpython@b2e5794 (original) (raw)
`@@ -17,11 +17,11 @@ common use. The second reason is to use Python as a component in a larger
`
17
17
`` application; this technique is generally referred to as :dfn:embedding Python
``
18
18
`in an application.
`
19
19
``
20
``
`-
Writing an extension module is a relatively well-understood process, where a
`
21
``
`-
"cookbook" approach works well. There are several tools that automate the
`
22
``
`-
process to some extent. While people have embedded Python in other
`
23
``
`-
applications since its early existence, the process of embedding Python is less
`
24
``
`-
straightforward than writing an extension.
`
``
20
`+
Writing an extension module is a relatively well-understood process, where a
`
``
21
`+
"cookbook" approach works well. There are several tools that automate the
`
``
22
`+
process to some extent. While people have embedded Python in other
`
``
23
`+
applications since its early existence, the process of embedding Python is
`
``
24
`+
less straightforward than writing an extension.
`
25
25
``
26
26
`Many API functions are useful independent of whether you're embedding or
`
27
27
`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
`
30
30
`application.
`
31
31
``
32
32
``
``
33
`+
Coding standards
`
``
34
`+
================
`
``
35
+
``
36
`+
If you're writing C code for inclusion in CPython, you must follow the
`
``
37
`` +
guidelines and standards defined in :PEP:7. These guidelines apply
``
``
38
`+
regardless of the version of Python you are contributing to. Following these
`
``
39
`+
conventions is not necessary for your own third party extension modules,
`
``
40
`+
unless you eventually expect to contribute them to Python.
`
``
41
+
``
42
+
33
43
`.. _api-includes:
`
34
44
``
35
45
`Include Files
`
``` @@ -81,6 +91,48 @@ header files do properly declare the entry points to be extern "C", so there
`81`
`91`
`is no need to do anything special to use the API from C++.
`
`82`
`92`
``
`83`
`93`
``
``
`94`
`+
Useful macros
`
``
`95`
`+
=============
`
``
`96`
`+`
``
`97`
`+
Several useful macros are defined in the Python header files. Many are
`
``
`98`
`` +
defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
``
``
`99`
`+
Others of a more general utility are defined here. This is not necessarily a
`
``
`100`
`+
complete listing.
`
``
`101`
`+`
``
`102`
`+
.. c:macro:: Py_UNREACHABLE()
`
``
`103`
`+`
``
`104`
`+
Use this when you have a code path that you do not expect to be reached.
`
``
`105`
``` +
For example, in the ``default:`` clause in a ``switch`` statement for which
``
106
all possible values are covered in ``case`` statements. Use this in places
``
107
where you might be tempted to put an ``assert(0)`` or ``abort()`` call.
``
108
+
``
109
`+
.. c:macro:: Py_ABS(x)
`
``
110
+
``
111
Return the absolute value of ``x``.
``
112
+
``
113
`+
.. c:macro:: Py_MIN(x, y)
`
``
114
+
``
115
Return the minimum value between ``x`` and ``y``.
``
116
+
``
117
`+
.. c:macro:: Py_MAX(x, y)
`
``
118
+
``
119
Return the maximum value between ``x`` and ``y``.
``
120
+
``
121
`+
.. c:macro:: Py_STRINGIFY(x)
`
``
122
+
``
123
Convert ``x`` to a C string. E.g. ``Py_STRINGIFY(123)`` returns
``
124
``"123"``.
``
125
+
``
126
`+
.. c:macro:: Py_MEMBER_SIZE(type, member)
`
``
127
+
``
128
Return the size of a structure (``type``) ``member`` in bytes.
``
129
+
``
130
`+
.. c:macro:: Py_CHARMASK(c)
`
``
131
+
``
132
`+
Argument must be a character or an integer in the range [-128, 127] or [0,
`
``
133
255]. This macro returns ``c`` cast to an ``unsigned char``.
``
134
+
``
135
+
84
136
`.. _api-objects:
`
85
137
``
86
138
`Objects, Types and Reference Counts
`