.. _allocating-objects:
-Allocating Objects on the Heap
+Allocating objects on the heap
==============================
To allocate and create extension modules.
-Deprecated aliases
-^^^^^^^^^^^^^^^^^^
+Soft-deprecated aliases
+^^^^^^^^^^^^^^^^^^^^^^^
-These are :term:`soft deprecated` aliases to existing functions and macros.
+.. soft-deprecated:: 3.15
+
+These are aliases to existing functions and macros.
They exist solely for backwards compatibility.
:widths: auto
:header-rows: 1
- * * Deprecated alias
+ * * Soft-deprecated alias
* Function
* * .. c:macro:: PyObject_NEW(type, typeobj)
* :c:macro:`PyObject_New`
*len* on success, and ``NULL`` on failure. If *v* is ``NULL``, the contents of
the bytes object are uninitialized.
- .. deprecated:: 3.15
- ``PyBytes_FromStringAndSize(NULL, len)`` is :term:`soft deprecated`,
- use the :c:type:`PyBytesWriter` API instead.
+ .. soft-deprecated:: 3.15
+ Use the :c:type:`PyBytesWriter` API instead of
+ ``PyBytes_FromStringAndSize(NULL, len)``.
.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)
*\*bytes* is set to ``NULL``, :exc:`MemoryError` is set, and ``-1`` is
returned.
- .. deprecated:: 3.15
- The function is :term:`soft deprecated`,
- use the :c:type:`PyBytesWriter` API instead.
+ .. soft-deprecated:: 3.15
+ Use the :c:type:`PyBytesWriter` API instead.
.. c:function:: PyObject *PyBytes_Repr(PyObject *bytes, int smartquotes)
``PyInit`` function
...................
-.. deprecated:: 3.15
+.. soft-deprecated:: 3.15
- This functionality is :term:`soft deprecated`.
- It will not get new features, but there are no plans to remove it.
+ This functionality will not get new features,
+ but there are no plans to remove it.
Instead of :c:func:`PyModExport_modulename`, an extension module can define
an older-style :dfn:`initialization function` with the signature:
Legacy single-phase initialization
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-.. deprecated:: 3.15
+.. soft-deprecated:: 3.15
- Single-phase initialization is :term:`soft deprecated`.
- It is a legacy mechanism to initialize extension
+ Single-phase initialization is a legacy mechanism to initialize extension
modules, with known drawbacks and design flaws. Extension module authors
are encouraged to use multi-phase initialization instead.
.. _fileobjects:
-File Objects
+File objects
------------
.. index:: pair: object; file
failure; the appropriate exception will be set.
-Deprecated API
-^^^^^^^^^^^^^^
+Soft-deprecated API
+^^^^^^^^^^^^^^^^^^^
+.. soft-deprecated:: 3.15
-These are :term:`soft deprecated` APIs that were included in Python's C API
+These are APIs that were included in Python's C API
by mistake. They are documented solely for completeness; use other
``PyFile*`` APIs instead.
It is equivalent to the :c:macro:`!INFINITY` macro from the C11 standard
``<math.h>`` header.
- .. deprecated:: 3.15
- The macro is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.15
.. c:macro:: Py_NAN
Equivalent to :c:macro:`!INFINITY`.
- .. deprecated:: 3.14
- The macro is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.14
.. c:macro:: Py_MATH_E
that is, it is normal, subnormal or zero, but not infinite or NaN.
Return ``0`` otherwise.
- .. deprecated:: 3.14
- The macro is :term:`soft deprecated`. Use :c:macro:`!isfinite` instead.
+ .. soft-deprecated:: 3.14
+ Use :c:macro:`!isfinite` instead.
.. c:macro:: Py_IS_INFINITY(X)
Return ``1`` if the given floating-point number *X* is positive or negative
infinity. Return ``0`` otherwise.
- .. deprecated:: 3.14
- The macro is :term:`soft deprecated`. Use :c:macro:`!isinf` instead.
+ .. soft-deprecated:: 3.14
+ Use :c:macro:`!isinf` instead.
.. c:macro:: Py_IS_NAN(X)
Return ``1`` if the given floating-point number *X* is a not-a-number (NaN)
value. Return ``0`` otherwise.
- .. deprecated:: 3.14
- The macro is :term:`soft deprecated`. Use :c:macro:`!isnan` instead.
+ .. soft-deprecated:: 3.14
+ Use :c:macro:`!isnan` instead.
Pack and Unpack functions
.. highlight:: c
-Frame Objects
+Frame objects
-------------
.. c:type:: PyFrameObject
Return the line number that *frame* is currently executing.
-Frame Locals Proxies
+Frame locals proxies
^^^^^^^^^^^^^^^^^^^^
.. versionadded:: 3.13
Return non-zero if *obj* is a frame :func:`locals` proxy.
-Legacy Local Variable APIs
+Legacy local variable APIs
^^^^^^^^^^^^^^^^^^^^^^^^^^
These APIs are :term:`soft deprecated`. As of Python 3.13, they do nothing.
.. c:function:: void PyFrame_LocalsToFast(PyFrameObject *f, int clear)
- This function is :term:`soft deprecated` and does nothing.
-
Prior to Python 3.13, this function would copy the :attr:`~frame.f_locals`
attribute of *f* to the internal "fast" array of local variables, allowing
changes in frame objects to be visible to the interpreter. If *clear* was
true, this function would process variables that were unset in the locals
dictionary.
- .. versionchanged:: 3.13
+ .. soft-deprecated:: 3.13
This function now does nothing.
.. c:function:: void PyFrame_FastToLocals(PyFrameObject *f)
- This function is :term:`soft deprecated` and does nothing.
-
Prior to Python 3.13, this function would copy the internal "fast" array
of local variables (which is used by the interpreter) to the
:attr:`~frame.f_locals` attribute of *f*, allowing changes in local
variables to be visible to frame objects.
- .. versionchanged:: 3.13
+ .. soft-deprecated:: 3.13
This function now does nothing.
.. c:function:: int PyFrame_FastToLocalsWithError(PyFrameObject *f)
- This function is :term:`soft deprecated` and does nothing.
-
Prior to Python 3.13, this function was similar to
:c:func:`PyFrame_FastToLocals`, but would return ``0`` on success, and
``-1`` with an exception set on failure.
- .. versionchanged:: 3.13
+ .. soft-deprecated:: 3.13
This function now does nothing.
:pep:`667`
-Internal Frames
+Internal frames
^^^^^^^^^^^^^^^
Unless using :pep:`523`, you will not need this.
Return the currently executing line number, or -1 if there is no line number.
.. versionadded:: 3.12
-
-
Use the standard ``alignas`` specifier rather than this macro.
- .. deprecated:: 3.15
- The macro is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.15
.. c:macro:: PY_FORMAT_SIZE_T
The :c:func:`printf` formatting modifier for :c:type:`size_t`.
Use ``"z"`` directly instead.
- .. deprecated:: 3.15
- The macro is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.15
.. c:macro:: Py_LL(number)
Py_ULL(number)
Consider using the C99 standard suffixes ``LL`` and ``LLU`` directly.
- .. deprecated:: 3.15
- The macro is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.15
.. c:macro:: PY_LONG_LONG
PY_INT32_T
respectively.
Historically, these types needed compiler-specific extensions.
- .. deprecated:: 3.15
- These macros are :term:`soft deprecated`.
+ .. soft-deprecated:: 3.15
.. c:macro:: PY_LLONG_MIN
PY_LLONG_MAX
The required header, ``<limits.h>``,
:ref:`is included <capi-system-includes>` in ``Python.h``.
- .. deprecated:: 3.15
- These macros are :term:`soft deprecated`.
+ .. soft-deprecated:: 3.15
.. c:macro:: Py_MEMCPY(dest, src, n)
This is a :term:`soft deprecated` alias to :c:func:`!memcpy`.
Use :c:func:`!memcpy` directly instead.
- .. deprecated:: 3.14
- The macro is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.14
.. c:macro:: Py_UNICODE_SIZE
The required header for the latter, ``<limits.h>``,
:ref:`is included <capi-system-includes>` in ``Python.h``.
- .. deprecated:: 3.15
- The macro is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.15
.. c:macro:: Py_UNICODE_WIDE
Defined if ``wchar_t`` can hold a Unicode character (UCS-4).
Use ``sizeof(wchar_t) >= 4`` instead
- .. deprecated:: 3.15
- The macro is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.15
.. c:macro:: Py_VA_COPY
.. versionchanged:: 3.6
This is now an alias to ``va_copy``.
- .. deprecated:: 3.15
- The macro is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.15
.. _api-objects:
.. c:function:: long PyLong_AS_LONG(PyObject *obj)
- A :term:`soft deprecated` alias.
Exactly equivalent to the preferred ``PyLong_AsLong``. In particular,
it can fail with :exc:`OverflowError` or another exception.
- .. deprecated:: 3.14
- The function is soft deprecated.
+ .. soft-deprecated:: 3.14
.. c:function:: int PyLong_AsInt(PyObject *obj)
// PyModule_AddObject() stole a reference to obj:
// Py_XDECREF(obj) is not needed here.
- .. deprecated:: 3.13
-
- :c:func:`PyModule_AddObject` is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.13
.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
.. versionadded:: 3.13
- .. deprecated:: 3.14
-
- This function is :term:`soft deprecated`.
+ .. soft-deprecated:: 3.14
Alias for :c:func:`PySequence_Contains`.
- .. deprecated:: 3.14
- The function is :term:`soft deprecated` and should no longer be used to
- write new code.
+ .. soft-deprecated:: 3.14
+ The function should no longer be used to write new code.
.. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
(or by) Python.
It is recommended to only use this function as a default or fallback,
- .. deprecated:: 3.15
+ .. soft-deprecated:: 3.15
- This function is :term:`soft deprecated`.
- It is kept for use in cases where it works, but not expected to be
- updated for additional platforms and configurations.
+ This function is kept for use in cases where it works, but not expected to
+ be updated for additional platforms and configurations.
On Linux, :func:`!find_library` tries to run external
programs (``/sbin/ldconfig``, ``gcc``, ``objdump`` and ``ld``) to find the
Floats with integral values (like ``5.0``) are no longer accepted in the
:func:`factorial` function.
-.. deprecated:: 3.15
- These aliases are :term:`soft deprecated` in favor of the
- :mod:`math.integer` functions.
+.. soft-deprecated:: 3.15
+ Use the :mod:`math.integer` functions instead of these aliases.
Constants
.. versionchanged:: 3.8
Added support for *url* being a :term:`path-like object`.
- .. deprecated:: 3.13
+ .. soft-deprecated:: 3.13
Passing a file path instead of URL is :term:`soft deprecated`.
Use :func:`guess_file_type` for this.
Use :class:`subprocess.Popen` or :func:`subprocess.run` to
control options like encodings.
- .. deprecated:: 3.14
- The function is :term:`soft deprecated` and should no longer be used to
- write new code. The :mod:`subprocess` module is recommended instead.
+ .. soft-deprecated:: 3.14
+ The :mod:`subprocess` module is recommended instead.
.. function:: posix_spawn(path, argv, env, *, file_actions=None, \
.. versionchanged:: 3.6
Accepts a :term:`path-like object`.
- .. deprecated:: 3.14
- These functions are :term:`soft deprecated` and should no longer be used
- to write new code. The :mod:`subprocess` module is recommended instead.
+ .. soft-deprecated:: 3.14
+ The :mod:`subprocess` module is recommended instead.
.. data:: P_NOWAIT
.. function:: prefixmatch(pattern, string, flags=0)
-.. function:: match(pattern, string, flags=0)
If zero or more characters at the beginning of *string* match the regular
expression *pattern*, return a corresponding :class:`~re.Match`. Return
:func:`~re.match`. Use that name when you need to retain compatibility with
older Python versions.
- .. deprecated:: 3.15
+ .. versionadded:: 3.15
+
+.. function:: match(pattern, string, flags=0)
+
+ .. soft-deprecated:: 3.15
:func:`~re.match` has been :term:`soft deprecated` in favor of
the alternate :func:`~re.prefixmatch` name of this API which is
more explicitly descriptive. Use it to better
.. method:: Pattern.prefixmatch(string[, pos[, endpos]])
-.. method:: Pattern.match(string[, pos[, endpos]])
If zero or more characters at the *beginning* of *string* match this regular
expression, return a corresponding :class:`~re.Match`. Return ``None`` if the
:meth:`~Pattern.match`. Use that name when you need to retain compatibility
with older Python versions.
- .. deprecated:: 3.15
+ .. versionadded:: 3.15
+
+.. method:: Pattern.match(string[, pos[, endpos]])
+
+ .. soft-deprecated:: 3.15
:meth:`~Pattern.match` has been :term:`soft deprecated` in favor of
the alternate :meth:`~Pattern.prefixmatch` name of this API which is
more explicitly descriptive. Use it to
.. versionadded:: 3.15
:func:`!prefixmatch`
-.. deprecated:: 3.15
- :func:`!match` is :term:`soft deprecated`
+.. soft-deprecated:: 3.15
+ :func:`!match`
Making a phonebook
^^^^^^^^^^^^^^^^^^
from __future__ import annotations
-from typing import TYPE_CHECKING
+import re
+from docutils import nodes
+from sphinx import addnodes
from sphinx.domains.changeset import (
VersionChange,
versionlabel_classes,
)
from sphinx.locale import _ as sphinx_gettext
+TYPE_CHECKING = False
if TYPE_CHECKING:
from docutils.nodes import Node
from sphinx.application import Sphinx
versionlabel_classes[self.name] = ""
+class SoftDeprecated(PyVersionChange):
+ """Directive for soft deprecations that auto-links to the glossary term.
+
+ Usage::
+
+ .. soft-deprecated:: 3.15
+
+ Use :func:`new_thing` instead.
+
+ Renders as: "Soft deprecated since version 3.15: Use new_thing() instead."
+ with "Soft deprecated" linking to the glossary definition.
+ """
+
+ _TERM_RE = re.compile(r":term:`([^`]+)`")
+
+ def run(self) -> list[Node]:
+ versionlabels[self.name] = sphinx_gettext(
+ ":term:`Soft deprecated` since version %s"
+ )
+ versionlabel_classes[self.name] = "soft-deprecated"
+ try:
+ result = super().run()
+ finally:
+ versionlabels[self.name] = ""
+ versionlabel_classes[self.name] = ""
+
+ for node in result:
+ # Add "versionchanged" class so existing theme CSS applies
+ node["classes"] = node.get("classes", []) + ["versionchanged"]
+ # Replace the plain-text "Soft deprecated" with a glossary reference
+ for inline in node.findall(nodes.inline):
+ if "versionmodified" in inline.get("classes", []):
+ self._add_glossary_link(inline)
+
+ return result
+
+ @classmethod
+ def _add_glossary_link(cls, inline: nodes.inline) -> None:
+ """Replace :term:`soft deprecated` text with a cross-reference to the
+ 'Soft deprecated' glossary entry."""
+ for child in inline.children:
+ if not isinstance(child, nodes.Text):
+ continue
+
+ text = str(child)
+ match = cls._TERM_RE.search(text)
+ if match is None:
+ continue
+
+ ref = addnodes.pending_xref(
+ "",
+ nodes.Text(match.group(1)),
+ refdomain="std",
+ reftype="term",
+ reftarget="soft deprecated",
+ refwarn=True,
+ )
+
+ start, end = match.span()
+ new_nodes: list[nodes.Node] = []
+ if start > 0:
+ new_nodes.append(nodes.Text(text[:start]))
+ new_nodes.append(ref)
+ if end < len(text):
+ new_nodes.append(nodes.Text(text[end:]))
+
+ child.parent.replace(child, new_nodes)
+ break
+
+
def setup(app: Sphinx) -> ExtensionMetadata:
# Override Sphinx's directives with support for 'next'
app.add_directive("versionadded", PyVersionChange, override=True)
# Register the ``.. deprecated-removed::`` directive
app.add_directive("deprecated-removed", DeprecatedRemoved)
+ # Register the ``.. soft-deprecated::`` directive
+ app.add_directive("soft-deprecated", SoftDeprecated)
+
return {
"version": "1.0",
"parallel_read_safe": True,
# HTML IDs excluded from the check-html-ids.py check.
+
+# Remove from here in 3.16
+c-api/allocation.html: deprecated-aliases
+c-api/file.html: deprecated-api
{% trans %}Deprecated since version %s, will be removed in version %s{% endtrans %}
{% trans %}Deprecated since version %s, removed in version %s{% endtrans %}
+{% trans %}:term:`Soft deprecated` since version %s{% endtrans %}
In docsbuild-scripts, when rewriting indexsidebar.html with actual versions:
projects / thirdparty / Python / cpython.git / commitdiff
