.. _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.10
+
+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`
.. _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.
.. 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
-
-
.. 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)
.. 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
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,
{% 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
