diff options
Diffstat (limited to 'Doc/c-api')
| -rw-r--r-- | Doc/c-api/arg.rst | 10 | ||||
| -rw-r--r-- | Doc/c-api/import.rst | 13 | ||||
| -rw-r--r-- | Doc/c-api/init_config.rst | 12 | ||||
| -rw-r--r-- | Doc/c-api/intro.rst | 15 | ||||
| -rw-r--r-- | Doc/c-api/object.rst | 18 | ||||
| -rw-r--r-- | Doc/c-api/refcounting.rst | 9 |
6 files changed, 49 insertions, 28 deletions
diff --git a/Doc/c-api/arg.rst b/Doc/c-api/arg.rst index 0b05e868917..3bbc990b632 100644 --- a/Doc/c-api/arg.rst +++ b/Doc/c-api/arg.rst @@ -274,7 +274,7 @@ small to receive the value. Convert a Python integer to a C :c:expr:`unsigned long` without overflow checking. - .. versionchanged:: next + .. versionchanged:: 3.14 Use :meth:`~object.__index__` if available. ``L`` (:class:`int`) [long long] @@ -284,7 +284,7 @@ small to receive the value. Convert a Python integer to a C :c:expr:`unsigned long long` without overflow checking. - .. versionchanged:: next + .. versionchanged:: 3.14 Use :meth:`~object.__index__` if available. ``n`` (:class:`int`) [:c:type:`Py_ssize_t`] @@ -380,10 +380,10 @@ Other objects The *converter* for the ``O&`` format unit in *items* must not store a borrowed buffer or a borrowed reference. - .. versionchanged:: next + .. versionchanged:: 3.14 :class:`str` and :class:`bytearray` objects no longer accepted as a sequence. - .. deprecated:: next + .. deprecated:: 3.14 Non-tuple sequences are deprecated if *items* contains format units which store a borrowed buffer or a borrowed reference. @@ -396,7 +396,7 @@ Other objects If the argument is not ``None``, it is parsed according to the specified format unit. - .. versionadded:: next + .. versionadded:: 3.14 A few other characters have a meaning in a format string. These may not occur inside nested parentheses. They are: diff --git a/Doc/c-api/import.rst b/Doc/c-api/import.rst index 1cab3ce3061..8eabc0406b1 100644 --- a/Doc/c-api/import.rst +++ b/Doc/c-api/import.rst @@ -16,19 +16,6 @@ Importing Modules This is a wrapper around :c:func:`PyImport_Import()` which takes a :c:expr:`const char *` as an argument instead of a :c:expr:`PyObject *`. -.. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name) - - This function is a deprecated alias of :c:func:`PyImport_ImportModule`. - - .. versionchanged:: 3.3 - This function used to fail immediately when the import lock was held - by another thread. In Python 3.3 though, the locking scheme switched - to per-module locks for most purposes, so this function's special - behaviour isn't needed anymore. - - .. deprecated-removed:: 3.13 3.15 - Use :c:func:`PyImport_ImportModule` instead. - .. c:function:: PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist) diff --git a/Doc/c-api/init_config.rst b/Doc/c-api/init_config.rst index bc5b236393b..e1931655618 100644 --- a/Doc/c-api/init_config.rst +++ b/Doc/c-api/init_config.rst @@ -363,7 +363,7 @@ Configuration Options - Read-only * - ``"import_time"`` - :c:member:`import_time <PyConfig.import_time>` - - ``bool`` + - ``int`` - Read-only * - ``"inspect"`` - :c:member:`inspect <PyConfig.inspect>` @@ -1477,13 +1477,19 @@ PyConfig .. c:member:: int import_time - If non-zero, profile import time. + If ``1``, profile import time. + If ``2``, include additional output that indicates + when an imported module has already been loaded. - Set the ``1`` by the :option:`-X importtime <-X>` option and the + Set by the :option:`-X importtime <-X>` option and the :envvar:`PYTHONPROFILEIMPORTTIME` environment variable. Default: ``0``. + .. versionchanged:: 3.14 + + Added support for ``import_time = 2`` + .. c:member:: int inspect Enter interactive mode after executing a script or a command. diff --git a/Doc/c-api/intro.rst b/Doc/c-api/intro.rst index c8c60eb9f48..2bad0bab224 100644 --- a/Doc/c-api/intro.rst +++ b/Doc/c-api/intro.rst @@ -826,14 +826,17 @@ frequently used builds will be described in the remainder of this section. Compiling the interpreter with the :c:macro:`!Py_DEBUG` macro defined produces what is generally meant by :ref:`a debug build of Python <debug-build>`. -:c:macro:`!Py_DEBUG` is enabled in the Unix build by adding -:option:`--with-pydebug` to the :file:`./configure` command. -It is also implied by the presence of the -not-Python-specific :c:macro:`!_DEBUG` macro. When :c:macro:`!Py_DEBUG` is enabled -in the Unix build, compiler optimization is disabled. + +On Unix, :c:macro:`!Py_DEBUG` can be enabled by adding :option:`--with-pydebug` +to the :file:`./configure` command. This will also disable compiler optimization. + +On Windows, selecting a debug build (e.g., by passing the :option:`-d` option to +:file:`PCbuild/build.bat`) automatically enables :c:macro:`!Py_DEBUG`. +Additionally, the presence of the not-Python-specific :c:macro:`!_DEBUG` macro, +when defined by the compiler, will also implicitly enable :c:macro:`!Py_DEBUG`. In addition to the reference count debugging described below, extra checks are -performed, see :ref:`Python Debug Build <debug-build>`. +performed. See :ref:`Python Debug Build <debug-build>` for more details. Defining :c:macro:`Py_TRACE_REFS` enables reference tracing (see the :option:`configure --with-trace-refs option <--with-trace-refs>`). diff --git a/Doc/c-api/object.rst b/Doc/c-api/object.rst index efad4d215b1..0fd159f1eb8 100644 --- a/Doc/c-api/object.rst +++ b/Doc/c-api/object.rst @@ -737,3 +737,21 @@ Object Protocol caller must hold a :term:`strong reference` to *obj* when calling this. .. versionadded:: 3.14 + +.. c:function:: int PyUnstable_Object_IsUniquelyReferenced(PyObject *op) + + Determine if *op* only has one reference. + + On GIL-enabled builds, this function is equivalent to + :c:expr:`Py_REFCNT(op) == 1`. + + On a :term:`free threaded <free threading>` build, this checks if *op*'s + :term:`reference count` is equal to one and additionally checks if *op* + is only used by this thread. :c:expr:`Py_REFCNT(op) == 1` is **not** + thread-safe on free threaded builds; prefer this function. + + The caller must hold an :term:`attached thread state`, despite the fact + that this function doesn't call into the Python interpreter. This function + cannot fail. + + .. versionadded:: 3.14 diff --git a/Doc/c-api/refcounting.rst b/Doc/c-api/refcounting.rst index 83febcf70a5..b23f016f9b0 100644 --- a/Doc/c-api/refcounting.rst +++ b/Doc/c-api/refcounting.rst @@ -23,7 +23,14 @@ of Python objects. Use the :c:func:`Py_SET_REFCNT()` function to set an object reference count. - See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`. + .. note:: + + On :term:`free threaded <free threading>` builds of Python, returning 1 + isn't sufficient to determine if it's safe to treat *o* as having no + access by other threads. Use :c:func:`PyUnstable_Object_IsUniquelyReferenced` + for that instead. + + See also the function :c:func:`PyUnstable_Object_IsUniqueReferencedTemporary()`. .. versionchanged:: 3.10 :c:func:`Py_REFCNT()` is changed to the inline static function. |