aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/Doc/c-api
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/c-api')
-rw-r--r--Doc/c-api/code.rst65
-rw-r--r--Doc/c-api/exceptions.rst438
-rw-r--r--Doc/c-api/structures.rst75
-rw-r--r--Doc/c-api/typeobj.rst11
-rw-r--r--Doc/c-api/veryhigh.rst8
5 files changed, 320 insertions, 277 deletions
diff --git a/Doc/c-api/code.rst b/Doc/c-api/code.rst
index 42594f063b0..717b0da8f87 100644
--- a/Doc/c-api/code.rst
+++ b/Doc/c-api/code.rst
@@ -211,6 +211,71 @@ bound into a function.
.. versionadded:: 3.12
+.. _c_codeobject_flags:
+
+Code Object Flags
+-----------------
+
+Code objects contain a bit-field of flags, which can be retrieved as the
+:attr:`~codeobject.co_flags` Python attribute (for example using
+:c:func:`PyObject_GetAttrString`), and set using a *flags* argument to
+:c:func:`PyUnstable_Code_New` and similar functions.
+
+Flags whose names start with ``CO_FUTURE_`` correspond to features normally
+selectable by :ref:`future statements <future>`. These flags can be used in
+:c:member:`PyCompilerFlags.cf_flags`.
+Note that many ``CO_FUTURE_`` flags are mandatory in current versions of
+Python, and setting them has no effect.
+
+The following flags are available.
+For their meaning, see the linked documentation of their Python equivalents.
+
+
+.. list-table::
+ :widths: auto
+ :header-rows: 1
+
+ * * Flag
+ * Meaning
+ * * .. c:macro:: CO_OPTIMIZED
+ * :py:data:`inspect.CO_OPTIMIZED`
+ * * .. c:macro:: CO_NEWLOCALS
+ * :py:data:`inspect.CO_NEWLOCALS`
+ * * .. c:macro:: CO_VARARGS
+ * :py:data:`inspect.CO_VARARGS`
+ * * .. c:macro:: CO_VARKEYWORDS
+ * :py:data:`inspect.CO_VARKEYWORDS`
+ * * .. c:macro:: CO_NESTED
+ * :py:data:`inspect.CO_NESTED`
+ * * .. c:macro:: CO_GENERATOR
+ * :py:data:`inspect.CO_GENERATOR`
+ * * .. c:macro:: CO_COROUTINE
+ * :py:data:`inspect.CO_COROUTINE`
+ * * .. c:macro:: CO_ITERABLE_COROUTINE
+ * :py:data:`inspect.CO_ITERABLE_COROUTINE`
+ * * .. c:macro:: CO_ASYNC_GENERATOR
+ * :py:data:`inspect.CO_ASYNC_GENERATOR`
+ * * .. c:macro:: CO_HAS_DOCSTRING
+ * :py:data:`inspect.CO_HAS_DOCSTRING`
+ * * .. c:macro:: CO_METHOD
+ * :py:data:`inspect.CO_METHOD`
+
+ * * .. c:macro:: CO_FUTURE_DIVISION
+ * no effect (:py:data:`__future__.division`)
+ * * .. c:macro:: CO_FUTURE_ABSOLUTE_IMPORT
+ * no effect (:py:data:`__future__.absolute_import`)
+ * * .. c:macro:: CO_FUTURE_WITH_STATEMENT
+ * no effect (:py:data:`__future__.with_statement`)
+ * * .. c:macro:: CO_FUTURE_PRINT_FUNCTION
+ * no effect (:py:data:`__future__.print_function`)
+ * * .. c:macro:: CO_FUTURE_UNICODE_LITERALS
+ * no effect (:py:data:`__future__.unicode_literals`)
+ * * .. c:macro:: CO_FUTURE_GENERATOR_STOP
+ * no effect (:py:data:`__future__.generator_stop`)
+ * * .. c:macro:: CO_FUTURE_ANNOTATIONS
+ * :py:data:`__future__.annotations`
+
+
Extra information
-----------------
diff --git a/Doc/c-api/exceptions.rst b/Doc/c-api/exceptions.rst
index a750cda3e2d..3ff4631a8e5 100644
--- a/Doc/c-api/exceptions.rst
+++ b/Doc/c-api/exceptions.rst
@@ -982,184 +982,135 @@ these are the C equivalent to :func:`reprlib.recursive_repr`.
.. _standardexceptions:
-Standard Exceptions
-===================
-
-All standard Python exceptions are available as global variables whose names are
-``PyExc_`` followed by the Python exception name. These have the type
-:c:expr:`PyObject*`; they are all class objects. For completeness, here are all
-the variables:
-
-.. index::
- single: PyExc_BaseException (C var)
- single: PyExc_BaseExceptionGroup (C var)
- single: PyExc_Exception (C var)
- single: PyExc_ArithmeticError (C var)
- single: PyExc_AssertionError (C var)
- single: PyExc_AttributeError (C var)
- single: PyExc_BlockingIOError (C var)
- single: PyExc_BrokenPipeError (C var)
- single: PyExc_BufferError (C var)
- single: PyExc_ChildProcessError (C var)
- single: PyExc_ConnectionAbortedError (C var)
- single: PyExc_ConnectionError (C var)
- single: PyExc_ConnectionRefusedError (C var)
- single: PyExc_ConnectionResetError (C var)
- single: PyExc_EOFError (C var)
- single: PyExc_FileExistsError (C var)
- single: PyExc_FileNotFoundError (C var)
- single: PyExc_FloatingPointError (C var)
- single: PyExc_GeneratorExit (C var)
- single: PyExc_ImportError (C var)
- single: PyExc_IndentationError (C var)
- single: PyExc_IndexError (C var)
- single: PyExc_InterruptedError (C var)
- single: PyExc_IsADirectoryError (C var)
- single: PyExc_KeyError (C var)
- single: PyExc_KeyboardInterrupt (C var)
- single: PyExc_LookupError (C var)
- single: PyExc_MemoryError (C var)
- single: PyExc_ModuleNotFoundError (C var)
- single: PyExc_NameError (C var)
- single: PyExc_NotADirectoryError (C var)
- single: PyExc_NotImplementedError (C var)
- single: PyExc_OSError (C var)
- single: PyExc_OverflowError (C var)
- single: PyExc_PermissionError (C var)
- single: PyExc_ProcessLookupError (C var)
- single: PyExc_PythonFinalizationError (C var)
- single: PyExc_RecursionError (C var)
- single: PyExc_ReferenceError (C var)
- single: PyExc_RuntimeError (C var)
- single: PyExc_StopAsyncIteration (C var)
- single: PyExc_StopIteration (C var)
- single: PyExc_SyntaxError (C var)
- single: PyExc_SystemError (C var)
- single: PyExc_SystemExit (C var)
- single: PyExc_TabError (C var)
- single: PyExc_TimeoutError (C var)
- single: PyExc_TypeError (C var)
- single: PyExc_UnboundLocalError (C var)
- single: PyExc_UnicodeDecodeError (C var)
- single: PyExc_UnicodeEncodeError (C var)
- single: PyExc_UnicodeError (C var)
- single: PyExc_UnicodeTranslateError (C var)
- single: PyExc_ValueError (C var)
- single: PyExc_ZeroDivisionError (C var)
-
-+-----------------------------------------+---------------------------------+----------+
-| C Name | Python Name | Notes |
-+=========================================+=================================+==========+
-| :c:data:`PyExc_BaseException` | :exc:`BaseException` | [1]_ |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_BaseExceptionGroup` | :exc:`BaseExceptionGroup` | [1]_ |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_Exception` | :exc:`Exception` | [1]_ |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | [1]_ |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_BlockingIOError` | :exc:`BlockingIOError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_BrokenPipeError` | :exc:`BrokenPipeError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_BufferError` | :exc:`BufferError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ChildProcessError` | :exc:`ChildProcessError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ConnectionAbortedError` | :exc:`ConnectionAbortedError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ConnectionError` | :exc:`ConnectionError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ConnectionRefusedError` | :exc:`ConnectionRefusedError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ConnectionResetError` | :exc:`ConnectionResetError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_EOFError` | :exc:`EOFError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_FileExistsError` | :exc:`FileExistsError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_FileNotFoundError` | :exc:`FileNotFoundError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_GeneratorExit` | :exc:`GeneratorExit` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ImportError` | :exc:`ImportError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_IndentationError` | :exc:`IndentationError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_IndexError` | :exc:`IndexError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_InterruptedError` | :exc:`InterruptedError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_IsADirectoryError` | :exc:`IsADirectoryError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_KeyError` | :exc:`KeyError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_LookupError` | :exc:`LookupError` | [1]_ |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ModuleNotFoundError` | :exc:`ModuleNotFoundError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_NameError` | :exc:`NameError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_NotADirectoryError` | :exc:`NotADirectoryError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_OSError` | :exc:`OSError` | [1]_ |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_PermissionError` | :exc:`PermissionError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ProcessLookupError` | :exc:`ProcessLookupError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_PythonFinalizationError` | :exc:`PythonFinalizationError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_RecursionError` | :exc:`RecursionError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_StopAsyncIteration` | :exc:`StopAsyncIteration` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_StopIteration` | :exc:`StopIteration` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_SystemError` | :exc:`SystemError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_TabError` | :exc:`TabError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_TimeoutError` | :exc:`TimeoutError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_TypeError` | :exc:`TypeError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_UnboundLocalError` | :exc:`UnboundLocalError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_UnicodeDecodeError` | :exc:`UnicodeDecodeError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_UnicodeEncodeError` | :exc:`UnicodeEncodeError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_UnicodeError` | :exc:`UnicodeError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_UnicodeTranslateError` | :exc:`UnicodeTranslateError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ValueError` | :exc:`ValueError` | |
-+-----------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | |
-+-----------------------------------------+---------------------------------+----------+
+Exception and warning types
+===========================
+
+All standard Python exceptions and warning categories are available as global
+variables whose names are ``PyExc_`` followed by the Python exception name.
+These have the type :c:expr:`PyObject*`; they are all class objects.
+
+For completeness, here are all the variables:
+
+Exception types
+---------------
+
+.. list-table::
+ :align: left
+ :widths: auto
+ :header-rows: 1
+
+ * * C name
+ * Python name
+ * * .. c:var:: PyObject *PyExc_BaseException
+ * :exc:`BaseException`
+ * * .. c:var:: PyObject *PyExc_BaseExceptionGroup
+ * :exc:`BaseExceptionGroup`
+ * * .. c:var:: PyObject *PyExc_Exception
+ * :exc:`Exception`
+ * * .. c:var:: PyObject *PyExc_ArithmeticError
+ * :exc:`ArithmeticError`
+ * * .. c:var:: PyObject *PyExc_AssertionError
+ * :exc:`AssertionError`
+ * * .. c:var:: PyObject *PyExc_AttributeError
+ * :exc:`AttributeError`
+ * * .. c:var:: PyObject *PyExc_BlockingIOError
+ * :exc:`BlockingIOError`
+ * * .. c:var:: PyObject *PyExc_BrokenPipeError
+ * :exc:`BrokenPipeError`
+ * * .. c:var:: PyObject *PyExc_BufferError
+ * :exc:`BufferError`
+ * * .. c:var:: PyObject *PyExc_ChildProcessError
+ * :exc:`ChildProcessError`
+ * * .. c:var:: PyObject *PyExc_ConnectionAbortedError
+ * :exc:`ConnectionAbortedError`
+ * * .. c:var:: PyObject *PyExc_ConnectionError
+ * :exc:`ConnectionError`
+ * * .. c:var:: PyObject *PyExc_ConnectionRefusedError
+ * :exc:`ConnectionRefusedError`
+ * * .. c:var:: PyObject *PyExc_ConnectionResetError
+ * :exc:`ConnectionResetError`
+ * * .. c:var:: PyObject *PyExc_EOFError
+ * :exc:`EOFError`
+ * * .. c:var:: PyObject *PyExc_FileExistsError
+ * :exc:`FileExistsError`
+ * * .. c:var:: PyObject *PyExc_FileNotFoundError
+ * :exc:`FileNotFoundError`
+ * * .. c:var:: PyObject *PyExc_FloatingPointError
+ * :exc:`FloatingPointError`
+ * * .. c:var:: PyObject *PyExc_GeneratorExit
+ * :exc:`GeneratorExit`
+ * * .. c:var:: PyObject *PyExc_ImportError
+ * :exc:`ImportError`
+ * * .. c:var:: PyObject *PyExc_IndentationError
+ * :exc:`IndentationError`
+ * * .. c:var:: PyObject *PyExc_IndexError
+ * :exc:`IndexError`
+ * * .. c:var:: PyObject *PyExc_InterruptedError
+ * :exc:`InterruptedError`
+ * * .. c:var:: PyObject *PyExc_IsADirectoryError
+ * :exc:`IsADirectoryError`
+ * * .. c:var:: PyObject *PyExc_KeyError
+ * :exc:`KeyError`
+ * * .. c:var:: PyObject *PyExc_KeyboardInterrupt
+ * :exc:`KeyboardInterrupt`
+ * * .. c:var:: PyObject *PyExc_LookupError
+ * :exc:`LookupError`
+ * * .. c:var:: PyObject *PyExc_MemoryError
+ * :exc:`MemoryError`
+ * * .. c:var:: PyObject *PyExc_ModuleNotFoundError
+ * :exc:`ModuleNotFoundError`
+ * * .. c:var:: PyObject *PyExc_NameError
+ * :exc:`NameError`
+ * * .. c:var:: PyObject *PyExc_NotADirectoryError
+ * :exc:`NotADirectoryError`
+ * * .. c:var:: PyObject *PyExc_NotImplementedError
+ * :exc:`NotImplementedError`
+ * * .. c:var:: PyObject *PyExc_OSError
+ * :exc:`OSError`
+ * * .. c:var:: PyObject *PyExc_OverflowError
+ * :exc:`OverflowError`
+ * * .. c:var:: PyObject *PyExc_PermissionError
+ * :exc:`PermissionError`
+ * * .. c:var:: PyObject *PyExc_ProcessLookupError
+ * :exc:`ProcessLookupError`
+ * * .. c:var:: PyObject *PyExc_PythonFinalizationError
+ * :exc:`PythonFinalizationError`
+ * * .. c:var:: PyObject *PyExc_RecursionError
+ * :exc:`RecursionError`
+ * * .. c:var:: PyObject *PyExc_ReferenceError
+ * :exc:`ReferenceError`
+ * * .. c:var:: PyObject *PyExc_RuntimeError
+ * :exc:`RuntimeError`
+ * * .. c:var:: PyObject *PyExc_StopAsyncIteration
+ * :exc:`StopAsyncIteration`
+ * * .. c:var:: PyObject *PyExc_StopIteration
+ * :exc:`StopIteration`
+ * * .. c:var:: PyObject *PyExc_SyntaxError
+ * :exc:`SyntaxError`
+ * * .. c:var:: PyObject *PyExc_SystemError
+ * :exc:`SystemError`
+ * * .. c:var:: PyObject *PyExc_SystemExit
+ * :exc:`SystemExit`
+ * * .. c:var:: PyObject *PyExc_TabError
+ * :exc:`TabError`
+ * * .. c:var:: PyObject *PyExc_TimeoutError
+ * :exc:`TimeoutError`
+ * * .. c:var:: PyObject *PyExc_TypeError
+ * :exc:`TypeError`
+ * * .. c:var:: PyObject *PyExc_UnboundLocalError
+ * :exc:`UnboundLocalError`
+ * * .. c:var:: PyObject *PyExc_UnicodeDecodeError
+ * :exc:`UnicodeDecodeError`
+ * * .. c:var:: PyObject *PyExc_UnicodeEncodeError
+ * :exc:`UnicodeEncodeError`
+ * * .. c:var:: PyObject *PyExc_UnicodeError
+ * :exc:`UnicodeError`
+ * * .. c:var:: PyObject *PyExc_UnicodeTranslateError
+ * :exc:`UnicodeTranslateError`
+ * * .. c:var:: PyObject *PyExc_ValueError
+ * :exc:`ValueError`
+ * * .. c:var:: PyObject *PyExc_ZeroDivisionError
+ * :exc:`ZeroDivisionError`
.. versionadded:: 3.3
:c:data:`PyExc_BlockingIOError`, :c:data:`PyExc_BrokenPipeError`,
@@ -1180,94 +1131,79 @@ the variables:
.. versionadded:: 3.11
:c:data:`PyExc_BaseExceptionGroup`.
-These are compatibility aliases to :c:data:`PyExc_OSError`:
-.. index::
- single: PyExc_EnvironmentError (C var)
- single: PyExc_IOError (C var)
- single: PyExc_WindowsError (C var)
+OSError aliases
+---------------
-+-------------------------------------+----------+
-| C Name | Notes |
-+=====================================+==========+
-| :c:data:`!PyExc_EnvironmentError` | |
-+-------------------------------------+----------+
-| :c:data:`!PyExc_IOError` | |
-+-------------------------------------+----------+
-| :c:data:`!PyExc_WindowsError` | [2]_ |
-+-------------------------------------+----------+
+The following are a compatibility aliases to :c:data:`PyExc_OSError`.
.. versionchanged:: 3.3
These aliases used to be separate exception types.
+.. list-table::
+ :align: left
+ :widths: auto
+ :header-rows: 1
+
+ * * C name
+ * Python name
+ * Notes
+ * * .. c:var:: PyObject *PyExc_EnvironmentError
+ * :exc:`OSError`
+ *
+ * * .. c:var:: PyObject *PyExc_IOError
+ * :exc:`OSError`
+ *
+ * * .. c:var:: PyObject *PyExc_WindowsError
+ * :exc:`OSError`
+ * [win]_
+
Notes:
-.. [1]
- This is a base class for other standard exceptions.
+.. [win]
+ :c:var:`!PyExc_WindowsError` is only defined on Windows; protect code that
+ uses this by testing that the preprocessor macro ``MS_WINDOWS`` is defined.
-.. [2]
- Only defined on Windows; protect code that uses this by testing that the
- preprocessor macro ``MS_WINDOWS`` is defined.
.. _standardwarningcategories:
-Standard Warning Categories
-===========================
-
-All standard Python warning categories are available as global variables whose
-names are ``PyExc_`` followed by the Python exception name. These have the type
-:c:expr:`PyObject*`; they are all class objects. For completeness, here are all
-the variables:
-
-.. index::
- single: PyExc_Warning (C var)
- single: PyExc_BytesWarning (C var)
- single: PyExc_DeprecationWarning (C var)
- single: PyExc_EncodingWarning (C var)
- single: PyExc_FutureWarning (C var)
- single: PyExc_ImportWarning (C var)
- single: PyExc_PendingDeprecationWarning (C var)
- single: PyExc_ResourceWarning (C var)
- single: PyExc_RuntimeWarning (C var)
- single: PyExc_SyntaxWarning (C var)
- single: PyExc_UnicodeWarning (C var)
- single: PyExc_UserWarning (C var)
-
-+------------------------------------------+---------------------------------+----------+
-| C Name | Python Name | Notes |
-+==========================================+=================================+==========+
-| :c:data:`PyExc_Warning` | :exc:`Warning` | [3]_ |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_BytesWarning` | :exc:`BytesWarning` | |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_DeprecationWarning` | :exc:`DeprecationWarning` | |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_EncodingWarning` | :exc:`EncodingWarning` | |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_FutureWarning` | :exc:`FutureWarning` | |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ImportWarning` | :exc:`ImportWarning` | |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_PendingDeprecationWarning`| :exc:`PendingDeprecationWarning`| |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_ResourceWarning` | :exc:`ResourceWarning` | |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_RuntimeWarning` | :exc:`RuntimeWarning` | |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_SyntaxWarning` | :exc:`SyntaxWarning` | |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_UnicodeWarning` | :exc:`UnicodeWarning` | |
-+------------------------------------------+---------------------------------+----------+
-| :c:data:`PyExc_UserWarning` | :exc:`UserWarning` | |
-+------------------------------------------+---------------------------------+----------+
+Warning types
+-------------
+
+.. list-table::
+ :align: left
+ :widths: auto
+ :header-rows: 1
+
+ * * C name
+ * Python name
+ * * .. c:var:: PyObject *PyExc_Warning
+ * :exc:`Warning`
+ * * .. c:var:: PyObject *PyExc_BytesWarning
+ * :exc:`BytesWarning`
+ * * .. c:var:: PyObject *PyExc_DeprecationWarning
+ * :exc:`DeprecationWarning`
+ * * .. c:var:: PyObject *PyExc_EncodingWarning
+ * :exc:`EncodingWarning`
+ * * .. c:var:: PyObject *PyExc_FutureWarning
+ * :exc:`FutureWarning`
+ * * .. c:var:: PyObject *PyExc_ImportWarning
+ * :exc:`ImportWarning`
+ * * .. c:var:: PyObject *PyExc_PendingDeprecationWarning
+ * :exc:`PendingDeprecationWarning`
+ * * .. c:var:: PyObject *PyExc_ResourceWarning
+ * :exc:`ResourceWarning`
+ * * .. c:var:: PyObject *PyExc_RuntimeWarning
+ * :exc:`RuntimeWarning`
+ * * .. c:var:: PyObject *PyExc_SyntaxWarning
+ * :exc:`SyntaxWarning`
+ * * .. c:var:: PyObject *PyExc_UnicodeWarning
+ * :exc:`UnicodeWarning`
+ * * .. c:var:: PyObject *PyExc_UserWarning
+ * :exc:`UserWarning`
.. versionadded:: 3.2
:c:data:`PyExc_ResourceWarning`.
.. versionadded:: 3.10
:c:data:`PyExc_EncodingWarning`.
-
-Notes:
-
-.. [3]
- This is a base class for other standard warning categories.
diff --git a/Doc/c-api/structures.rst b/Doc/c-api/structures.rst
index 987bc167c68..58dd915e04f 100644
--- a/Doc/c-api/structures.rst
+++ b/Doc/c-api/structures.rst
@@ -28,18 +28,52 @@ under :ref:`reference counting <countingrefs>`.
object. In a normal "release" build, it contains only the object's
reference count and a pointer to the corresponding type object.
Nothing is actually declared to be a :c:type:`PyObject`, but every pointer
- to a Python object can be cast to a :c:expr:`PyObject*`. Access to the
- members must be done by using the macros :c:macro:`Py_REFCNT` and
- :c:macro:`Py_TYPE`.
+ to a Python object can be cast to a :c:expr:`PyObject*`.
+
+ The members must not be accessed directly; instead use macros such as
+ :c:macro:`Py_REFCNT` and :c:macro:`Py_TYPE`.
+
+ .. c:member:: Py_ssize_t ob_refcnt
+
+ The object's reference count, as returned by :c:macro:`Py_REFCNT`.
+ Do not use this field directly; instead use functions and macros such as
+ :c:macro:`!Py_REFCNT`, :c:func:`Py_INCREF` and :c:func:`Py_DecRef`.
+
+ The field type may be different from ``Py_ssize_t``, depending on
+ build configuration and platform.
+
+ .. c:member:: PyTypeObject* ob_type
+
+ The object's type.
+ Do not use this field directly; use :c:macro:`Py_TYPE` and
+ :c:func:`Py_SET_TYPE` instead.
.. c:type:: PyVarObject
- This is an extension of :c:type:`PyObject` that adds the :c:member:`~PyVarObject.ob_size`
- field. This is only used for objects that have some notion of *length*.
- This type does not often appear in the Python/C API.
- Access to the members must be done by using the macros
- :c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, and :c:macro:`Py_SIZE`.
+ An extension of :c:type:`PyObject` that adds the
+ :c:member:`~PyVarObject.ob_size` field.
+ This is intended for objects that have some notion of *length*.
+
+ As with :c:type:`!PyObject`, the members must not be accessed directly;
+ instead use macros such as :c:macro:`Py_SIZE`, :c:macro:`Py_REFCNT` and
+ :c:macro:`Py_TYPE`.
+
+ .. c:member:: Py_ssize_t ob_size
+
+ A size field, whose contents should be considered an object's internal
+ implementation detail.
+
+ Do not use this field directly; use :c:macro:`Py_SIZE` instead.
+
+ Object creation functions such as :c:func:`PyObject_NewVar` will
+ generally set this field to the requested size (number of items).
+ After creation, arbitrary values can be stored in :c:member:`!ob_size`
+ using :c:macro:`Py_SET_SIZE`.
+
+ To get an object's publicly exposed length, as returned by
+ the Python function :py:func:`len`, use :c:func:`PyObject_Length`
+ instead.
.. c:macro:: PyObject_HEAD
@@ -103,9 +137,8 @@ under :ref:`reference counting <countingrefs>`.
Get the type of the Python object *o*.
- Return a :term:`borrowed reference`.
-
- Use the :c:func:`Py_SET_TYPE` function to set an object type.
+ The returned reference is :term:`borrowed <borrowed reference>` from *o*.
+ Do not release it with :c:func:`Py_DECREF` or similar.
.. versionchanged:: 3.11
:c:func:`Py_TYPE()` is changed to an inline static function.
@@ -122,16 +155,26 @@ under :ref:`reference counting <countingrefs>`.
.. c:function:: void Py_SET_TYPE(PyObject *o, PyTypeObject *type)
- Set the object *o* type to *type*.
+ Set the type of object *o* to *type*, without any checking or reference
+ counting.
+
+ This is a very low-level operation.
+ Consider instead setting the Python attribute :attr:`~object.__class__`
+ using :c:func:`PyObject_SetAttrString` or similar.
+
+ Note that assigning an incompatible type can lead to undefined behavior.
+
+ If *type* is a :ref:`heap type <heap-types>`, the caller must create a
+ new reference to it.
+ Similarly, if the old type of *o* is a heap type, the caller must release
+ a reference to that type.
.. versionadded:: 3.9
.. c:function:: Py_ssize_t Py_SIZE(PyVarObject *o)
- Get the size of the Python object *o*.
-
- Use the :c:func:`Py_SET_SIZE` function to set an object size.
+ Get the :c:member:`~PyVarObject.ob_size` field of *o*.
.. versionchanged:: 3.11
:c:func:`Py_SIZE()` is changed to an inline static function.
@@ -140,7 +183,7 @@ under :ref:`reference counting <countingrefs>`.
.. c:function:: void Py_SET_SIZE(PyVarObject *o, Py_ssize_t size)
- Set the object *o* size to *size*.
+ Set the :c:member:`~PyVarObject.ob_size` field of *o* to *size*.
.. versionadded:: 3.9
diff --git a/Doc/c-api/typeobj.rst b/Doc/c-api/typeobj.rst
index af2bead3bb5..060d6f60174 100644
--- a/Doc/c-api/typeobj.rst
+++ b/Doc/c-api/typeobj.rst
@@ -492,9 +492,9 @@ metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that it
type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
-.. c:member:: Py_ssize_t PyObject.ob_refcnt
+:c:member:`PyObject.ob_refcnt`
- This is the type object's reference count, initialized to ``1`` by the
+ The type object's reference count is initialized to ``1`` by the
``PyObject_HEAD_INIT`` macro. Note that for :ref:`statically allocated type
objects <static-types>`, the type's instances (objects whose :c:member:`~PyObject.ob_type`
points back to the type) do *not* count as references. But for
@@ -506,7 +506,7 @@ type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
This field is not inherited by subtypes.
-.. c:member:: PyTypeObject* PyObject.ob_type
+:c:member:`PyObject.ob_type`
This is the type's type, in other words its metatype. It is initialized by the
argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be
@@ -532,14 +532,13 @@ type objects) *must* have the :c:member:`~PyVarObject.ob_size` field.
PyVarObject Slots
-----------------
-.. c:member:: Py_ssize_t PyVarObject.ob_size
+:c:member:`PyVarObject.ob_size`
For :ref:`statically allocated type objects <static-types>`, this should be
initialized to zero. For :ref:`dynamically allocated type objects
<heap-types>`, this field has a special internal meaning.
- This field should be accessed using the :c:func:`Py_SIZE()` and
- :c:func:`Py_SET_SIZE()` macros.
+ This field should be accessed using the :c:func:`Py_SIZE()` macro.
**Inheritance:**
diff --git a/Doc/c-api/veryhigh.rst b/Doc/c-api/veryhigh.rst
index 1ef4181d52e..fb07fec7eff 100644
--- a/Doc/c-api/veryhigh.rst
+++ b/Doc/c-api/veryhigh.rst
@@ -361,7 +361,7 @@ the same library that the Python runtime is using.
:py:mod:`!ast` Python module, which exports these constants under
the same names.
- .. c:var:: int CO_FUTURE_DIVISION
-
- This bit can be set in *flags* to cause division operator ``/`` to be
- interpreted as "true division" according to :pep:`238`.
+ The "``PyCF``" flags above can be combined with "``CO_FUTURE``" flags such
+ as :c:macro:`CO_FUTURE_ANNOTATIONS` to enable features normally
+ selectable using :ref:`future statements <future>`.
+ See :ref:`c_codeobject_flags` for a complete list.