Deploying to gh-pages from @ 09d77bf 🚀

Author: mattwang44

.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: bdfb3041d251008c4c431e304e0b21c1
+config: 908a2225ab805924400df1aecc1bf46b
 tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/c-api/arg.rst.txt

@@ -152,6 +152,48 @@ There are three ways strings and buffers can be converted to C:
    attempting any conversion.  Raises :exc:`TypeError` if the object is not
    a :class:`bytearray` object. The C variable may also be declared as :c:expr:`PyObject*`.
 
+``u`` (:class:`str`) [const Py_UNICODE \*]
+   Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of
+   Unicode characters.  You must pass the address of a :c:type:`Py_UNICODE`
+   pointer variable, which will be filled with the pointer to an existing
+   Unicode buffer.  Please note that the width of a :c:type:`Py_UNICODE`
+   character depends on compilation options (it is either 16 or 32 bits).
+   The Python string must not contain embedded null code points; if it does,
+   a :exc:`ValueError` exception is raised.
+
+   .. versionchanged:: 3.5
+      Previously, :exc:`TypeError` was raised when embedded null code points
+      were encountered in the Python string.
+
+   .. deprecated-removed:: 3.3 3.12
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``u#`` (:class:`str`) [const Py_UNICODE \*, :c:type:`Py_ssize_t`]
+   This variant on ``u`` stores into two C variables, the first one a pointer to a
+   Unicode data buffer, the second one its length.  This variant allows
+   null code points.
+
+   .. deprecated-removed:: 3.3 3.12
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``Z`` (:class:`str` or ``None``) [const Py_UNICODE \*]
+   Like ``u``, but the Python object may also be ``None``, in which case the
+   :c:type:`Py_UNICODE` pointer is set to ``NULL``.
+
+   .. deprecated-removed:: 3.3 3.12
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``Z#`` (:class:`str` or ``None``) [const Py_UNICODE \*, :c:type:`Py_ssize_t`]
+   Like ``u#``, but the Python object may also be ``None``, in which case the
+   :c:type:`Py_UNICODE` pointer is set to ``NULL``.
+
+   .. deprecated-removed:: 3.3 3.12
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
 ``U`` (:class:`str`) [PyObject \*]
    Requires that the Python object is a Unicode object, without attempting
    any conversion.  Raises :exc:`TypeError` if the object is not a Unicode
@@ -221,11 +263,6 @@ There are three ways strings and buffers can be converted to C:
    them. Instead, the implementation assumes that the byte string object uses the
    encoding passed in as parameter.
 
-.. versionchanged:: 3.12
-   ``u``, ``u#``, ``Z``, and ``Z#`` are removed because they used a legacy
-   ``Py_UNICODE*`` representation.
-
-
 Numbers
 -------
 

_sources/c-api/bool.rst.txt

@@ -6,7 +6,7 @@ Boolean Objects
 ---------------
 
 Booleans in Python are implemented as a subclass of integers.  There are only
-two booleans, :c:data:`Py_False` and :c:data:`Py_True`.  As such, the normal
+two booleans, :const:`Py_False` and :const:`Py_True`.  As such, the normal
 creation and deletion functions don't apply to booleans.  The following macros
 are available, however.
 
@@ -19,32 +19,29 @@ are available, however.
 
 .. c:var:: PyObject* Py_False
 
-   The Python ``False`` object.  This object has no methods and is
-   `immortal <https://peps.python.org/pep-0683/>`_.
-
-.. versionchanged:: 3.12
-   :c:data:`Py_False` is immortal.
+   The Python ``False`` object.  This object has no methods.  It needs to be
+   treated just like any other object with respect to reference counts.
 
 
 .. c:var:: PyObject* Py_True
 
-   The Python ``True`` object.  This object has no methods and is
-   `immortal <https://peps.python.org/pep-0683/>`_.
-
-.. versionchanged:: 3.12
-   :c:data:`Py_True` is immortal.
+   The Python ``True`` object.  This object has no methods.  It needs to be treated
+   just like any other object with respect to reference counts.
 
 
 .. c:macro:: Py_RETURN_FALSE
 
-   Return :c:data:`Py_False` from a function.
+   Return :const:`Py_False` from a function, properly incrementing its reference
+   count.
 
 
 .. c:macro:: Py_RETURN_TRUE
 
-   Return :c:data:`Py_True` from a function.
+   Return :const:`Py_True` from a function, properly incrementing its reference
+   count.
 
 
 .. c:function:: PyObject* PyBool_FromLong(long v)
 
-   Return :c:data:`Py_True` or :c:data:`Py_False`, depending on the truth value of *v*.
+   Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
+   truth value of *v*.

_sources/c-api/bytes.rst.txt

@@ -58,6 +58,9 @@ called with a non-bytes parameter.
 
    .. % XXX: This should be exactly the same as the table in PyErr_Format.
    .. % One should just refer to the other.
+   .. % XXX: The descriptions for %zd and %zu are wrong, but the truth is complicated
+   .. % because not all compilers support the %z width modifier -- we fake it
+   .. % when necessary via interpolating PY_FORMAT_SIZE_T.
 
    .. tabularcolumns:: |l|l|L|
 

_sources/c-api/call.rst.txt

@@ -57,15 +57,6 @@ This bears repeating:
    A class supporting vectorcall **must** also implement
    :c:member:`~PyTypeObject.tp_call` with the same semantics.
 
-.. versionchanged:: 3.12
-
-   The :const:`Py_TPFLAGS_HAVE_VECTORCALL` flag is now removed from a class
-   when the class's :py:meth:`~object.__call__` method is reassigned.
-   (This internally sets :c:member:`~PyTypeObject.tp_call` only, and thus
-   may make it behave differently than the vectorcall function.)
-   In earlier Python versions, vectorcall should only be used with
-   :const:`immutable <Py_TPFLAGS_IMMUTABLETYPE>` or static types.
-
 A class should not implement vectorcall if that would be slower
 than *tp_call*. For example, if the callee needs to convert
 the arguments to an args tuple and kwargs dict anyway, then there is no point
@@ -93,7 +84,7 @@ This is a pointer to a function with the following signature:
    and they must be unique.
    If there are no keyword arguments, then *kwnames* can instead be *NULL*.
 
-.. data:: PY_VECTORCALL_ARGUMENTS_OFFSET
+.. c:macro:: PY_VECTORCALL_ARGUMENTS_OFFSET
 
    If this flag is set in a vectorcall *nargsf* argument, the callee is allowed
    to temporarily change ``args[-1]``. In other words, *args* points to

_sources/c-api/code.rst.txt

@@ -33,47 +33,28 @@ bound into a function.
 
    Return the number of free variables in *co*.
 
-.. c:function:: PyCodeObject* PyUnstable_Code_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
+.. c:function:: PyCodeObject* PyCode_New(int argcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
 
    Return a new code object.  If you need a dummy code object to create a frame,
-   use :c:func:`PyCode_NewEmpty` instead.
-
-   Since the definition of the bytecode changes often, calling
-   :c:func:`PyCode_New` directly can bind you to a precise Python version.
-
-   The many arguments of this function are inter-dependent in complex
+   use :c:func:`PyCode_NewEmpty` instead.  Calling :c:func:`PyCode_New` directly
+   will bind you to a precise Python version since the definition of the bytecode
+   changes often. The many arguments of this function are inter-dependent in complex
    ways, meaning that subtle changes to values are likely to result in incorrect
    execution or VM crashes. Use this function only with extreme care.
 
    .. versionchanged:: 3.11
       Added ``exceptiontable`` parameter.
 
-   .. index:: single: PyCode_New
-
-   .. versionchanged:: 3.12
-
-      Renamed from ``PyCode_New`` as part of :ref:`unstable-c-api`.
-      The old name is deprecated, but will remain available until the
-      signature changes again.
-
-.. c:function:: PyCodeObject* PyUnstable_Code_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
+.. c:function:: PyCodeObject* PyCode_NewWithPosOnlyArgs(int argcount, int posonlyargcount, int kwonlyargcount, int nlocals, int stacksize, int flags, PyObject *code, PyObject *consts, PyObject *names, PyObject *varnames, PyObject *freevars, PyObject *cellvars, PyObject *filename, PyObject *name, int firstlineno, PyObject *linetable, PyObject *exceptiontable)
 
    Similar to :c:func:`PyCode_New`, but with an extra "posonlyargcount" for positional-only arguments.
    The same caveats that apply to ``PyCode_New`` also apply to this function.
 
-   .. index:: single: PyCode_NewWithPosOnlyArgs
-
-   .. versionadded:: 3.8 as ``PyCode_NewWithPosOnlyArgs``
+   .. versionadded:: 3.8
 
    .. versionchanged:: 3.11
       Added ``exceptiontable`` parameter.
 
-   .. versionchanged:: 3.12
-
-      Renamed to ``PyUnstable_Code_NewWithPosOnlyArgs``.
-      The old name is deprecated, but will remain available until the
-      signature changes again.
-
 .. c:function:: PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
 
    Return a new empty code object with the specified filename,
@@ -136,129 +117,3 @@ bound into a function.
    the free variables. On error, ``NULL`` is returned and an exception is raised.
 
    .. versionadded:: 3.11
-
-.. c:function:: int PyCode_AddWatcher(PyCode_WatchCallback callback)
-
-   Register *callback* as a code object watcher for the current interpreter.
-   Return an ID which may be passed to :c:func:`PyCode_ClearWatcher`.
-   In case of error (e.g. no more watcher IDs available),
-   return ``-1`` and set an exception.
-
-   .. versionadded:: 3.12
-
-.. c:function:: int PyCode_ClearWatcher(int watcher_id)
-
-   Clear watcher identified by *watcher_id* previously returned from
-   :c:func:`PyCode_AddWatcher` for the current interpreter.
-   Return ``0`` on success, or ``-1`` and set an exception on error
-   (e.g. if the given *watcher_id* was never registered.)
-
-   .. versionadded:: 3.12
-
-.. c:type:: PyCodeEvent
-
-   Enumeration of possible code object watcher events:
-   - ``PY_CODE_EVENT_CREATE``
-   - ``PY_CODE_EVENT_DESTROY``
-
-   .. versionadded:: 3.12
-
-.. c:type:: int (*PyCode_WatchCallback)(PyCodeEvent event, PyCodeObject* co)
-
-   Type of a code object watcher callback function.
-
-   If *event* is ``PY_CODE_EVENT_CREATE``, then the callback is invoked
-   after `co` has been fully initialized. Otherwise, the callback is invoked
-   before the destruction of *co* takes place, so the prior state of *co*
-   can be inspected.
-
-   If *event* is ``PY_CODE_EVENT_DESTROY``, taking a reference in the callback
-   to the about-to-be-destroyed code object will resurrect it and prevent it
-   from being freed at this time. When the resurrected object is destroyed
-   later, any watcher callbacks active at that time will be called again.
-
-   Users of this API should not rely on internal runtime implementation
-   details. Such details may include, but are not limited to, the exact
-   order and timing of creation and destruction of code objects. While
-   changes in these details may result in differences observable by watchers
-   (including whether a callback is invoked or not), it does not change
-   the semantics of the Python code being executed.
-
-   If the callback sets an exception, it must return ``-1``; this exception will
-   be printed as an unraisable exception using :c:func:`PyErr_WriteUnraisable`.
-   Otherwise it should return ``0``.
-
-   There may already be a pending exception set on entry to the callback. In
-   this case, the callback should return ``0`` with the same exception still
-   set. This means the callback may not call any other API that can set an
-   exception unless it saves and clears the exception state first, and restores
-   it before returning.
-
-   .. versionadded:: 3.12
-
-
-Extra information
------------------
-
-To support low-level extensions to frame evaluation, such as external
-just-in-time compilers, it is possible to attach arbitrary extra data to
-code objects.
-
-These functions are part of the unstable C API tier:
-this functionality is a CPython implementation detail, and the API
-may change without deprecation warnings.
-
-.. c:function:: Py_ssize_t PyUnstable_Eval_RequestCodeExtraIndex(freefunc free)
-
-   Return a new an opaque index value used to adding data to code objects.
-
-   You generally call this function once (per interpreter) and use the result
-   with ``PyCode_GetExtra`` and ``PyCode_SetExtra`` to manipulate
-   data on individual code objects.
-
-   If *free* is not ``NULL``: when a code object is deallocated,
-   *free* will be called on non-``NULL`` data stored under the new index.
-   Use :c:func:`Py_DecRef` when storing :c:type:`PyObject`.
-
-   .. index:: single: _PyEval_RequestCodeExtraIndex
-
-   .. versionadded:: 3.6 as ``_PyEval_RequestCodeExtraIndex``
-
-   .. versionchanged:: 3.12
-
-     Renamed to ``PyUnstable_Eval_RequestCodeExtraIndex``.
-     The old private name is deprecated, but will be available until the API
-     changes.
-
-.. c:function:: int PyUnstable_Code_GetExtra(PyObject *code, Py_ssize_t index, void **extra)
-
-   Set *extra* to the extra data stored under the given index.
-   Return 0 on success. Set an exception and return -1 on failure.
-
-   If no data was set under the index, set *extra* to ``NULL`` and return
-   0 without setting an exception.
-
-   .. index:: single: _PyCode_GetExtra
-
-   .. versionadded:: 3.6 as ``_PyCode_GetExtra``
-
-   .. versionchanged:: 3.12
-
-     Renamed to ``PyUnstable_Code_GetExtra``.
-     The old private name is deprecated, but will be available until the API
-     changes.
-
-.. c:function:: int PyUnstable_Code_SetExtra(PyObject *code, Py_ssize_t index, void *extra)
-
-   Set the extra data stored under the given index to *extra*.
-   Return 0 on success. Set an exception and return -1 on failure.
-
-   .. index:: single: _PyCode_SetExtra
-
-   .. versionadded:: 3.6 as ``_PyCode_SetExtra``
-
-   .. versionchanged:: 3.12
-
-     Renamed to ``PyUnstable_Code_SetExtra``.
-     The old private name is deprecated, but will be available until the API
-     changes.