8000 Merge branch 'main' into fix/uuid/mac-address-libuuid-132710 · python/cpython@fd84b3c · GitHub
[go: up one dir, main page]
Skip to content

Commit fd84b3c

Browse files
picnixzpicnixz
authored
Merge branch 'main' into fix/uuid/mac-address-libuuid-132710
2 parents 03bcfad + 7b1a700 commit fd84b3c

File tree

397 files changed

+11757
-4937
lines changed
  • lifecycle.rst
  • memory.rst
  • objimpl.rst
  • type.rst
  • typeobj.rst
  • conf.py
  • glossary.rst
  • howto
  • library
  • reference
  • tools
  • tutorial
  • using
  • whatsnew
  • Include
  • Lib
  • Makefile.pre.in
  • Misc
  • Modules
  • Objects
  • PCbuild
  • PC
  • Programs
  • Python
  • Tools
  • configure.ac
  • configure

    • Some content is hidden

    Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

    397 files changed

    +11757
    -4937
    lines changed

    ‎.gitattributes

    Lines changed: 2 additions & 0 deletions
    Original file line numberDiff line numberDiff line change
    @@ -10,6 +10,7 @@
    1010
    *.ico binary
    1111
    *.jpg binary
    1212
    *.pck binary
    13+
    *.pdf binary
    1314
    *.png binary
    1415
    *.psd binary
    1516
    *.tar binary
    @@ -67,6 +68,7 @@ PCbuild/readme.txt dos
    6768
    **/clinic/*.cpp.h generated
    6869
    **/clinic/*.h.h generated
    6970
    *_db.h generated
    71+
    Doc/c-api/lifecycle.dot.svg generated
    7072
    Doc/data/stable_abi.dat generated
    7173
    Doc/library/token-list.inc generated
    7274
    Include/internal/pycore_ast.h generated

    ‎.github/workflows/build.yml

    Lines changed: 7 additions & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -15,7 +15,13 @@ permissions:
    1515
    contents: read
    1616

    1717
    concurrency:
    18-
    group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}-reusable
    18+
    # https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions#concurrency
    19+
    # 'group' must be a key uniquely representing a PR or push event.
    20+
    # github.workflow is the workflow name
    21+
    # github.actor is the user invoking the workflow
    22+
    # github.head_ref is the source branch of the PR or otherwise blank
    23+
    # github.run_id is a unique number for the current run
    24+
    group: ${{ github.workflow }}-${{ github.actor }}-${{ github.head_ref || github.run_id }}
    1925
    cancel-in-progress: true
    2026

    2127
    env:

    ‎Doc/c-api/allocation.rst

    Lines changed: 107 additions & 25 deletions
    Original file line numberDiff line numberDiff line change
    @@ -16,46 +16,128 @@ Allocating Objects on the Heap
    1616
    1717
    Initialize a newly allocated object *op* with its type and initial
    1818
    reference. Returns the initialized object. Other fields of the object are
    19-
    not affected.
    19+
    not initialized. Despite its name, this function is unrelated to the
    20+
    object's :meth:`~object.__init__` method (:c:member:`~PyTypeObject.tp_init`
    21+
    slot). Specifically, this function does **not** call the object's
    22+
    :meth:`!__init__` method.
    23+
    24+
    In general, consider this function to be a low-level routine. Use
    25+
    :c:member:`~PyTypeObject.tp_alloc` where possible.
    26+
    For implementing :c:member:`!tp_alloc` for your type, prefer
    27+
    :c:func:`PyType_GenericAlloc` or :c:func:`PyObject_New`.
    28+
    29+
    .. note::
    30+
    31+
    This function only initializes the object's memory corresponding to the
    32+
    initial :c:type:`PyObject` structure. It does not zero the rest.
    2033
    2134
    2235
    .. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
    2336
    2437
    This does everything :c:func:`PyObject_Init` does, and also initializes the
    2538
    length information for a variable-size object.
    2639
    40+
    .. note::
    41+
    42+
    This function only initializes some of the object's memory. It does not
    43+
    zero the rest.
    44+
    2745
    2846
    .. c:macro:: PyObject_New(TYPE, typeobj)
    2947
    30-
    Allocate a new Python object using the C structure type *TYPE*
    31-
    and the Python type object *typeobj* (``PyTypeObject*``).
    32-
    Fields not defined by the Python object header are not initialized.
    33-
    The caller will own the only reference to the object
    34-
    (i.e. its reference count will be one).
    35-
    The size of the memory allocation is determined from the
    36-
    :c:member:`~PyTypeObject.tp_basicsize` field of the type object.
    48+
    Allocates a new Python object using the C structure type *TYPE* and the
    49+
    Python type object *typeobj* (``PyTypeObject*``) by calling
    50+
    :c:func:`PyObject_Malloc` to allocate memory and initializing it like
    51+
    :c:func:`PyObject_Init`. The caller will own the only reference to the
    52+
    object (i.e. its reference count will be one).
    53+
    54+
    Avoid calling this directly to allocate memory for an object; call the type's
    55+
    :c:member:`~PyTypeObject.tp_alloc` slot instead.
    56+
    57+
    When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
    58+
    :c:func:`PyType_GenericAlloc` is preferred over a custom function that
    59+
    simply calls this macro.
    60+
    61+
    This macro does not call :c:member:`~PyTypeObject.tp_alloc`,
    62+
    :c:member:`~PyTypeObject.tp_new` (:meth:`~object.__new__`), or
    63+
    :c:member:`~PyTypeObject.tp_init` (:meth:`~object.__init__`).
    64+
    65+
    This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
    66+
    :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_New` instead.
    67+
    68+
    Memory allocated by this macro must be freed with :c:func:`PyObject_Free`
    69+
    (usually called via the object's :c:member:`~PyTypeObject.tp_free` slot).
    70+
    71+
    .. note::
    72+
    73+
    The returned memory is not guaranteed to have been completely zeroed
    74+
    before it was initialized.
    75+
    76+
    .. note::
    77+
    78+
    This macro does not construct a fully initialized object of the given
    79+
    type; it merely allocates memory and prepares it for further
    80+
    initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
    81+
    fully initialized object, call *typeobj* instead. For example::
    82+
    83+
    PyObject *foo = PyObject_CallNoArgs((PyObject *)&PyFoo_Type);
    3784
    38-
    Note that this function is unsuitable if *typeobj* has
    39-
    :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
    40-
    use :c:func:`PyObject_GC_New` instead.
    85+
    .. seealso::
    86+
    87+
    * :c:func:`PyObject_Free`
    88+
    * :c:macro:`PyObject_GC_New`
    89+
    * :c:func:`PyType_GenericAlloc`
    90+
    * :c:member:`~PyTypeObject.tp_alloc`
    4191

    4292

    4393
    .. c:macro:: PyObject_NewVar(TYPE, typeobj, size)
    4494
    45-
    Allocate a new Python object using the C structure type *TYPE* and the
    46-
    Python type object *typeobj* (``PyTypeObject*``).
    47-
    Fields not defined by the Python object header
    48-
    are not initialized. The allocated memory allows for the *TYPE* structure
    49-
    plus *size* (``Py_ssize_t``) fields of the size
    50-
    given by the :c:member:`~PyTypeObject.tp_itemsize` field of
    51-
    *typeobj*. This is useful for implementing objects like tuples, which are
    52-
    able to determine their size at construction time. Embedding the array of
    53-
    fields into the same allocation decreases the number of allocations,
    54-
    improving the memory management efficiency.
    55-
    56-
    Note that this function is unsuitable if *typeobj* has
    57-
    :c:macro:`Py_TPFLAGS_HAVE_GC` set. For such objects,
    58-
    use :c:func:`PyObject_GC_NewVar` instead.
    95+
    Like :c:macro:`PyObject_New` except:
    96+
    97+
    * It allocates enough memory for the *TYPE* structure plus *size*
    98+
    (``Py_ssize_t``) fields of the size given by the
    99+
    :c:member:`~PyTypeObject.tp_itemsize` field of *typeobj*.
    100+
    * The memory is initialized like :c:func:`PyObject_InitVar`.
    101+
    102+
    This is useful for implementing objects like tuples, which are able to
    103+
    determine their size at construction time. Embedding the array of fields
    104+
    into the same allocation decreases the number of allocations, improving the
    105+
    memory management efficiency.
    106+
    107+
    Avoid calling this directly to allocate memory for an object; call the type's
    108+
    :c:member:`~PyTypeObject.tp_alloc` slot instead.
    109+
    110+
    When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
    111+
    :c:func:`PyType_GenericAlloc` is preferred over a custom function that
    112+
    simply calls this macro.
    113+
    114+
    This cannot be used for objects with :c:macro:`Py_TPFLAGS_HAVE_GC` set in
    115+
    :c:member:`~PyTypeObject.tp_flags`; use :c:macro:`PyObject_GC_NewVar`
    116+
    instead.
    117+
    118+
    Memory allocated by this function must be freed with :c:func:`PyObject_Free`
    119+
    (usually called via the object's :c:member:`~PyTypeObject.tp_free` slot).
    120+
    121+
    .. note::
    122+
    123+
    The returned memory is not guaranteed to have been completely zeroed
    124+
    before it was initialized.
    125+
    126+
    .. note::
    127+
    128+
    This macro does not construct a fully initialized object of the given
    129+
    type; it merely allocates memory and prepares it for further
    130+
    initialization by :c:member:`~PyTypeObject.tp_init`. To construct a
    131+
    fully initialized object, call *typeobj* instead. For example::
    132+
    133+
    PyObject *list_instance = PyObject_CallNoArgs((PyObject *)&PyList_Type);
    134+
    135+
    .. seealso::
    136+
    137+
    * :c:func:`PyObject_Free`
    138+
    * :c:macro:`PyObject_GC_NewVar`
    139+
    * :c:func:`PyType_GenericAlloc`
    140+
    * :c:member:`~PyTypeObject.tp_alloc`
    59141

    60142

    61143
    .. c:function:: void PyObject_Del(void *op)

    ‎Doc/c-api/code.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -182,7 +182,7 @@ bound into a function.
    182182
    Type of a code object watcher callback function.
    183183
    184184
    If *event* is ``PY_CODE_EVENT_CREATE``, then the callback is invoked
    185-
    after `co` has been fully initialized. Otherwise, the callback is invoked
    185+
    after *co* has been fully initialized. Otherwise, the callback is invoked
    186186
    before the destruction of *co* takes place, so the prior state of *co*
    187187
    can be inspected.
    188188

    ‎Doc/c-api/function.rst

    Lines changed: 1 addition & 1 deletion
    Original file line numberDiff line numberDiff line change
    @@ -169,7 +169,7 @@ There are a few functions specific to Python functions.
    169169
    unpredictable effects, including infinite recursion.
    170170
    171171
    If *event* is ``PyFunction_EVENT_CREATE``, then the callback is invoked
    172-
    after `func` has been fully initialized. Otherwise, the callback is invoked
    172+
    after *func* has been fully initialized. Otherwise, the callback is invoked
    173173
    before the modification to *func* takes place, so the prior state of *func*
    174174
    can be inspected. The runtime is permitted to optimize away the creation of
    175175
    function objects when possible. In such cases no event will be emitted.

    ‎Doc/c-api/gcsupport.rst

    Lines changed: 57 additions & 0 deletions
    Original file line numberDiff line numberDiff line change
    @@ -57,11 +57,49 @@ rules:
    5757
    Analogous to :c:macro:`PyObject_New` but for container objects with the
    5858
    :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
    5959

    60+
    Do not call this directly to allocate memory for an object; call the type's
    61+ 57AE
    :c:member:`~PyTypeObject.tp_alloc` slot instead.
    62+
    63+
    When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
    64+
    :c:func:`PyType_GenericAlloc` is preferred over a custom function that
    65+
    simply calls this macro.
    66+
    67+
    Memory allocated by this macro must be freed with
    68+
    :c:func:`PyObject_GC_Del` (usually called via the object's
    69+
    :c:member:`~PyTypeObject.tp_free` slot).
    70+
    71+
    .. seealso::
    72+
    73+
    * :c:func:`PyObject_GC_Del`
    74+
    * :c:macro:`PyObject_New`
    75+
    * :c:func:`PyType_GenericAlloc`
    76+
    * :c:member:`~PyTypeObject.tp_alloc`
    77+
    78+
    6079
    .. c:macro:: PyObject_GC_NewVar(TYPE, typeobj, size)
    6180
    6281
    Analogous to :c:macro:`PyObject_NewVar` but for container objects with the
    6382
    :c:macro:`Py_TPFLAGS_HAVE_GC` flag set.
    6483

    84+
    Do not call this directly to allocate memory for an object; call the type's
    85+
    :c:member:`~PyTypeObject.tp_alloc` slot instead.
    86+
    87+
    When populating a type's :c:member:`~PyTypeObject.tp_alloc` slot,
    88+
    :c:func:`PyType_GenericAlloc` is preferred over a custom function that
    89+
    simply calls this macro.
    90+
    91+
    Memory allocated by this macro must be freed with
    92+
    :c:func:`PyObject_GC_Del` (usually called via the object's
    93+
    :c:member:`~PyTypeObject.tp_free` slot).
    94+
    95+
    .. seealso::
    96+
    97+
    * :c:func:`PyObject_GC_Del`
    98+
    * :c:macro:`PyObject_NewVar`
    99+
    * :c:func:`PyType_GenericAlloc`
    100+
    * :c:member:`~PyTypeObject.tp_alloc`
    101+
    102+
    65103
    .. c:function:: PyObject* PyUnstable_Object_GC_NewWithExtraData(PyTypeObject *type, size_t extra_size)
    66104
    67105
    Analogous to :c:macro:`PyObject_GC_New` but allocates *extra_size*
    @@ -73,6 +111,10 @@ rules:
    73111
    The extra data will be deallocated with the object, but otherwise it is
    74112
    not managed by Python.
    75113
    114+
    Memory allocated by this function must be freed with
    115+
    :c:func:`PyObject_GC_Del` (usually called via the object's
    116+
    :c:member:`~PyTypeObject.tp_free` slot).
    117+
    76118
    .. warning::
    77119
    The function is marked as unstable because the final mechanism
    78120
    for reserving extra data after an instance is not yet decided.
    @@ -136,6 +178,21 @@ rules:
    136178
    Releases memory allocated to an object using :c:macro:`PyObject_GC_New` or
    137179
    :c:macro:`PyObject_GC_NewVar`.
    138180
    181+
    Do not call this directly to free an object's memory; call the type's
    182+
    :c:member:`~PyTypeObject.tp_free` slot instead.
    183+
    184+
    Do not use this for memory allocated by :c:macro:`PyObject_New`,
    185+
    :c:macro:`PyObject_NewVar`, or related allocation functions; use
    186+
    :c:func:`PyObject_Free` instead.
    187+
    188+
    .. seealso::
    189+
    190+
    * :c:func:`PyObject_Free` is the non-GC equivalent of this function.
    191+
    * :c:macro:`PyObject_GC_New`
    192+
    * :c:macro:`PyObject_GC_NewVar`
    193+
    * :c:func:`PyType_GenericAlloc`
    194+
    * :c:member:`~PyTypeObject.tp_free`
    195+
    139196
    140197
    .. c:function:: void PyObject_GC_UnTrack(void *op)
    141198

    0 commit comments

    Comments
     (0)
    0