@@ -105,45 +105,63 @@ defined closer to where they are useful (e.g. :c:macro:`Py_RETURN_NONE`).
105105Others of a more general utility are defined here. This is not necessarily a
106106complete listing.
107107
108- ..c :macro ::Py_UNREACHABLE( )
108+ ..c :macro ::Py_ABS(x )
109109
110-
111- For example, in the ``default: `` clause in a ``switch `` statement for which
112- all possible values are covered in ``case `` statements. Use this in places
113- where you might be tempted to put an ``assert(0) `` or ``abort() `` call.
110+ x ``.
114111
115- In release mode, the macro helps the compiler to optimize the code, and
116- avoids a warning about unreachable code. For example, the macro is
117- implemented with ``__builtin_unreachable() `` on GCC in release mode.
112+ ..versionadded ::3.3
118113
119- A use for ``Py_UNREACHABLE() `` is following a call a function that
120- never returns but that is not declared:c:macro: `_Py_NO_RETURN `.
114+ ..c :macro :: Py_CHARMASK(c)
121115
122- If a code path is very unlikely code but can be reached under exceptional
123- case, this macro must not be used. For example, under low memory condition
124- or if a system call returns a value out of the expected range. In this
125- case, it's better to report the error to the caller. If the error cannot
126- be reported to caller,:c:func: `Py_FatalError ` can be used.
116+
117+ 255]. This macro returns ``c `` cast to an ``unsigned char ``.
127118
128- versionadded :: 3.7
119+ ..c : macro :: Py_DEPRECATED(version)
129120
130- ..c :macro :: Py_ABS(x)
121+
122+ symbol name.
131123
132- x ``.
124+ Example::
125+
126+ Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
127+
128+ ..versionchanged ::3.8
129+ MSVC support was added.
130+
131+ ..c :macro :: Py_GETENV(s)
132+
133+ getenv(s) ``, but returns ``NULL `` if:option: `-E ` was passed on the
134+ command line (i.e. if ``Py_IgnoreEnvironmentFlag `` is set).
135+
136+ ..c :macro :: Py_MAX(x, y)
137+
138+ x `` and ``y ``.
133139
134140 ..versionadded ::3.3
135141
142+ ..c :macro :: Py_MEMBER_SIZE(type, member)
143+
144+ type ``) ``member `` in bytes.
145+
146+ ..versionadded ::3.6
147+
136148..c :macro :: Py_MIN(x, y)
137149
138150x `` and ``y ``.
139151
140152 ..versionadded ::3.3
141153
142- ..c :macro ::Py_MAX(x, y)
154+ ..c :macro ::Py_NO_INLINE
143155
144- x `` and ``y ``.
156+
157+ consumption: useful on LTO+PGO builds which heavily inline code (see
158+ :issue: `33720 `).
145159
146- ..versionadded ::3.3
160+ Usage::
161+
162+ Py_NO_INLINE static int random(void) { return 4; }
163+
164+ ..versionadded ::3.11
147165
148166..c :macro :: Py_STRINGIFY(x)
149167
@@ -152,21 +170,27 @@ complete listing.
152170
153171 ..versionadded ::3.4
154172
155- ..c :macro :: Py_MEMBER_SIZE(type, member)
156-
157- type ``) ``member `` in bytes.
173+ ..c :macro :: Py_UNREACHABLE()
158174
159- ..versionadded ::3.6
175+
176+ For example, in the ``default: `` clause in a ``switch `` statement for which
177+ all possible values are covered in ``case `` statements. Use this in places
178+ where you might be tempted to put an ``assert(0) `` or ``abort() `` call.
160179
161- ..c :macro :: Py_CHARMASK(c)
180+ In release mode, the macro helps the compiler to optimize the code, and
181+ avoids a warning about unreachable code. For example, the macro is
182+ implemented with ``__builtin_unreachable() `` on GCC in release mode.
162183
163- Argument must be a character or an integer in the range [-128, 127] or [0,
164- 255]. This macro returns`` c `` cast to an `` unsigned char ` `.
184+ A use for `` Py_UNREACHABLE() `` is following a call a function that
185+ never returnsbut that is not declared :c:macro: ` _Py_NO_RETURN `.
165186
166- ..c :macro :: Py_GETENV(s)
187+ If a code path is very unlikely code but can be reached under exceptional
188+ case, this macro must not be used. For example, under low memory condition
189+ or if a system call returns a value out of the expected range. In this
190+ case, it's better to report the error to the caller. If the error cannot
191+ be reported to caller,:c:func: `Py_FatalError ` can be used.
167192
168- getenv(s) ``, but returns ``NULL `` if:option: `-E ` was passed on the
169- command line (i.e. if ``Py_IgnoreEnvironmentFlag `` is set).
193+ ..versionadded ::3.7
170194
171195..c :macro :: Py_UNUSED(arg)
172196
@@ -175,18 +199,6 @@ complete listing.
175199
176200 ..versionadded ::3.4
177201
178- ..c :macro :: Py_DEPRECATED(version)
179-
180-
181- symbol name.
182-
183- Example::
184-
185- Py_DEPRECATED(3.8) PyAPI_FUNC(int) Py_OldFunction(void);
186-
187- ..versionchanged ::3.8
188- MSVC support was added.
189-
190202..c :macro :: PyDoc_STRVAR(name, str)
191203
192204name `` that can be used in docstrings.
@@ -221,6 +233,7 @@ complete listing.
221233 {NULL, NULL}
222234 };
223235
236+
224237.. _api-objects :
225238
226239Objects, Types and Reference Counts