Commits

larry committed aa20b52 Merge

Merge the heads from Clinic and current trunk together. Hooray.

Comments (0)

Files changed (1003)

 Doc/tools/pygments/
 Doc/tools/sphinx/
 Lib/lib2to3/*.pickle
+Lib/test/data/*
 Lib/_sysconfigdata.py
 Lib/plat-mac/errors.rsrc.df.rsrc
 Makefile
 Makefile.pre
 Misc/python.pc
+Misc/python-config.sh
 Modules/Setup
 Modules/Setup.config
 Modules/Setup.local
 pybuilddir.txt
 pyconfig.h
 python
+python-config
+python-config.py
 python.exe
 python-gdb.py
 python.exe-gdb.py
 .gdb_history
 .purify
 .svn/
-DS_Store
+.DS_Store
 Makefile$
 Makefile.pre$
 TAGS$
 Modules/config.c
 Modules/ld_so_aix$
 Parser/pgen$
+^lcov-report/
 ^core
 ^python-gdb.py
 ^python.exe-gdb.py
 .coverage
 coverage/
 htmlcov/
+*.gcda
+*.gcno
+*.gcov
+coverage.info
 7085403daf439adb3f9e70ef13f6bedb1c447376 v3.2.3rc1
 428f05cb7277e1d42bb9dd8d1af6b6270ebc6112 v3.2.3rc2
 3d0686d90f55a78f96d9403da2c52dc2411419d0 v3.2.3
+b2cb7bc1edb8493c0a78f9331eae3e8fba6a881d v3.2.4rc1
+1e10bdeabe3de02f038a63c001911561ac1d13a7 v3.2.4
 f1a9a6505731714f0e157453ff850e3b71615c45 v3.3.0a1
 2f69db52d6de306cdaef0a0cc00cc823fb350b01 v3.3.0a2
 0b53b70a40a00013505eb35e3660057b62be77be v3.3.0a3
 88a0792e8ba3e4916b24c7e7a522c277d326d66e v3.3.0rc2
 c191d21cefafb3832c45570e84854e309aa62eaa v3.3.0rc3
 bd8afb90ebf28ba4edc901d4a235f75e7bbc79fd v3.3.0
+92c2cfb924055ce68c4f78f836dcfe688437ceb8 v3.3.1rc1
+d9893d13c6289aa03d33559ec67f97dcbf5c9e3c v3.3.1
+d047928ae3f6314a13b6137051315453d0ae89b6 v3.3.2
+46535f65e7f3bcdcf176f36d34bc1fed719ffd2b v3.4.0a1
 Python/opcode_targets.h: Python/makeopcodetargets.py Lib/opcode.py
 
 Objects/typeslots.inc: Include/typeslots.h Objects/typeslots.py
+
+Include/graminit.h: Grammar/Grammar Parser/acceler.c Parser/grammar1.c Parser/listnode.c Parser/node.c Parser/parser.c Parser/bitset.c Parser/metagrammar.c Parser/firstsets.c Parser/grammar.c Parser/pgen.c Objects/obmalloc.c Python/dynamic_annotations.c Python/mysnprintf.c Python/pyctype.c Parser/tokenizer_pgen.c Parser/printgrammar.c Parser/parsetok_pgen.c Parser/pgenmain.c
+Python/graminit.c: Include/graminit.h Grammar/Grammar Parser/acceler.c Parser/grammar1.c Parser/listnode.c Parser/node.c Parser/parser.c Parser/bitset.c Parser/metagrammar.c Parser/firstsets.c Parser/grammar.c Parser/pgen.c Objects/obmalloc.c Python/dynamic_annotations.c Python/mysnprintf.c Python/pyctype.c Parser/tokenizer_pgen.c Parser/printgrammar.c Parser/parsetok_pgen.c Parser/pgenmain.c

Doc/c-api/allocation.rst

    Allocate a new Python object using the C structure type *TYPE* and the
    Python type object *type*.  Fields not defined by the Python object header
    are not initialized; the object's reference count will be one.  The size of
-   the memory allocation is determined from the :attr:`tp_basicsize` field of
+   the memory allocation is determined from the :c:member:`~PyTypeObject.tp_basicsize` field of
    the type object.
 
 
    Allocate a new Python object using the C structure type *TYPE* and the
    Python type object *type*.  Fields not defined by the Python object header
    are not initialized.  The allocated memory allows for the *TYPE* structure
-   plus *size* fields of the size given by the :attr:`tp_itemsize` field of
+   plus *size* fields of the size given by the :c:member:`~PyTypeObject.tp_itemsize` field of
    *type*.  This is useful for implementing objects like tuples, which are
    able to determine their size at construction time.  Embedding the array of
    fields into the same allocation decreases the number of allocations,
 
    Releases memory allocated to an object using :c:func:`PyObject_New` or
    :c:func:`PyObject_NewVar`.  This is normally called from the
-   :attr:`tp_dealloc` handler specified in the object's type.  The fields of
+   :c:member:`~PyTypeObject.tp_dealloc` handler specified in the object's type.  The fields of
    the object should not be accessed after this call as the memory is no
    longer a valid Python object.
 

Doc/c-api/apiabiversion.rst

+.. highlightlang:: c
+
+.. _apiabiversion:
+
+***********************
+API and ABI Versioning
+***********************
+
+``PY_VERSION_HEX`` is the Python version number encoded in a single integer.
+
+For example if the ``PY_VERSION_HEX`` is set to ``0x030401a2``, the underlying
+version information can be found by treating it as a 32 bit number in
+the following manner:
+
+   +-------+-------------------------+------------------------------------------------+
+   | Bytes | Bits (big endian order) | Meaning                                        |
+   +=======+=========================+================================================+
+   | ``1`` |       ``1-8``           |  ``PY_MAJOR_VERSION`` (the ``3`` in            |
+   |       |                         |  ``3.4.1a2``)                                  |
+   +-------+-------------------------+------------------------------------------------+
+   | ``2`` |       ``9-16``          |  ``PY_MINOR_VERSION`` (the ``4`` in            |
+   |       |                         |  ``3.4.1a2``)                                  |
+   +-------+-------------------------+------------------------------------------------+
+   | ``3`` |       ``17-24``         |  ``PY_MICRO_VERSION`` (the ``1`` in            |
+   |       |                         |  ``3.4.1a2``)                                  |
+   +-------+-------------------------+------------------------------------------------+
+   | ``4`` |       ``25-28``         |  ``PY_RELEASE_LEVEL`` (``0xA`` for alpha,      |
+   |       |                         |  ``0xB`` for beta, ``0xC`` for release         |
+   |       |                         |  candidate and ``0xF`` for final), in this     |
+   |       |                         |  case it is alpha.                             |
+   +-------+-------------------------+------------------------------------------------+
+   |       |       ``29-32``         |  ``PY_RELEASE_SERIAL`` (the ``2`` in           |
+   |       |                         |  ``3.4.1a2``, zero for final releases)         |
+   +-------+-------------------------+------------------------------------------------+
+
+Thus ``3.4.1a2`` is hexversion ``0x030401a2``.
+
+All the given macros are defined in :source:`Include/patchlevel.h`.
+

Doc/c-api/arg.rst

       as *converter*.
 
 ``s*`` (:class:`str`, :class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer]
-   This format accepts Unicode objects as well as objects supporting the
-   buffer protocol.
+   This format accepts Unicode objects as well as :term:`bytes-like object`\ s.
    It fills a :c:type:`Py_buffer` structure provided by the caller.
    In this case the resulting C string may contain embedded NUL bytes.
    Unicode objects are converted to C strings using ``'utf-8'`` encoding.
    contain embedded NUL bytes; if it does, a :exc:`TypeError`
    exception is raised.
 
-``y*`` (:class:`bytes`, :class:`bytearray` or buffer compatible object) [Py_buffer]
-   This variant on ``s*`` doesn't accept Unicode objects, only objects
-   supporting the buffer protocol.  **This is the recommended way to accept
+``y*`` (:class:`bytes`, :class:`bytearray` or :term:`bytes-like object`) [Py_buffer]
+   This variant on ``s*`` doesn't accept Unicode objects, only
+   :term:`bytes-like object`\ s.  **This is the recommended way to accept
    binary data.**
 
 ``y#`` (:class:`bytes`) [const char \*, int]
-   This variant on ``s#`` doesn't accept Unicode objects, only bytes-like
-   objects.
+   This variant on ``s#`` doesn't accept Unicode objects, only :term:`bytes-like
+   object`\ s.
 
 ``S`` (:class:`bytes`) [PyBytesObject \*]
    Requires that the Python object is a :class:`bytes` object, without

Doc/c-api/buffer.rst

 in decreasing order of complexity. Note that each flag contains all bits
 of the flags below it.
 
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|
 
 +-----------------------------+-------+---------+------------+
 |  Request                    | shape | strides | suboffsets |
 C or Fortran contiguity can be explicitly requested, with and without stride
 information. Without stride information, the buffer must be C-contiguous.
 
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|
+
 +-----------------------------------+-------+---------+------------+--------+
 |  Request                          | shape | strides | suboffsets | contig |
 +===================================+=======+=========+============+========+
 In the following table *U* stands for undefined contiguity. The consumer would
 have to call :c:func:`PyBuffer_IsContiguous` to determine contiguity.
 
-
+.. tabularcolumns:: |p{0.35\linewidth}|l|l|l|l|l|l|
 
 +-------------------------------+-------+---------+------------+--------+----------+--------+
 |  Request                      | shape | strides | suboffsets | contig | readonly | format |

Doc/c-api/bytearray.rst

 .. c:function:: PyObject* PyByteArray_FromObject(PyObject *o)
 
    Return a new bytearray object from any object, *o*, that implements the
-   buffer protocol.
+   :ref:`buffer protocol <bufferobjects>`.
 
    .. XXX expand about the buffer protocol, at least somewhere
 

Doc/c-api/bytes.rst

    .. % because not all compilers support the %z width modifier -- we fake it
    .. % when necessary via interpolating PY_FORMAT_SIZE_T.
 
+   .. tabularcolumns:: |l|l|L|
+
    +-------------------+---------------+--------------------------------+
    | Format Characters | Type          | Comment                        |
    +===================+===============+================================+

Doc/c-api/dict.rst

    :c:type:`char\*`, rather than a :c:type:`PyObject\*`.
 
 
+.. c:function:: PyObject* PyDict_SetDefault(PyObject *p, PyObject *key, PyObject *default)
+
+   This is the same as the Python-level :meth:`dict.setdefault`.  If present, it
+   returns the value corresponding to *key* from the dictionary *p*.  If the key
+   is not in the dict, it is inserted with value *defaultobj* and *defaultobj*
+   is returned.  This function evaluates the hash function of *key* only once,
+   instead of evaluating it independently for the lookup and the insertion.
+
+
 .. c:function:: PyObject* PyDict_Items(PyObject *p)
 
    Return a :c:type:`PyListObject` containing all the items from the dictionary.

Doc/c-api/exceptions.rst

    when the system call returns an error.
 
 
+.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject)
+
+   Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
+   *filenameObject* is not *NULL*, it is passed to the constructor of *type* as
+   a third parameter.  In the case of exceptions such as :exc:`IOError` and
+   :exc:`OSError`, this is used to define the :attr:`filename` attribute of the
+   exception instance.
+
+
 .. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename)
 
-   Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if
-   *filename* is not *NULL*, it is passed to the constructor of *type* as a third
-   parameter.  In the case of exceptions such as :exc:`IOError` and :exc:`OSError`,
-   this is used to define the :attr:`filename` attribute of the exception instance.
-   *filename* is decoded from the filesystem encoding
+   Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename
+   is given as a C string.  *filename* is decoded from the filesystem encoding
    (:func:`sys.getfilesystemencoding`).
 
 
    specifying the exception type to be raised. Availability: Windows.
 
 
+.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject)
+
+   Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior
+   that if *filenameObject* is not *NULL*, it is passed to the constructor of
+   :exc:`WindowsError` as a third parameter.  Availability: Windows.
+
+
 .. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename)
 
-   Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that
-   if *filename* is not *NULL*, it is passed to the constructor of
-   :exc:`WindowsError` as a third parameter.  *filename* is decoded from the
-   filesystem encoding (:func:`sys.getfilesystemencoding`).  Availability:
-   Windows.
+   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the
+   filename is given as a C string.  *filename* is decoded from the filesystem
+   encoding (:func:`sys.getfilesystemencoding`).  Availability: Windows.
 
 
-.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename)
+.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename)
+
+   Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an
+   additional parameter specifying the exception type to be raised.
+   Availability: Windows.
+
+
+.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename)
 
    Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional
    parameter specifying the exception type to be raised. Availability: Windows.
    Ends a :c:func:`Py_EnterRecursiveCall`.  Must be called once for each
    *successful* invocation of :c:func:`Py_EnterRecursiveCall`.
 
-Properly implementing :attr:`tp_repr` for container types requires
+Properly implementing :c:member:`~PyTypeObject.tp_repr` for container types requires
 special recursion handling.  In addition to protecting the stack,
-:attr:`tp_repr` also needs to track objects to prevent cycles.  The
+:c:member:`~PyTypeObject.tp_repr` also needs to track objects to prevent cycles.  The
 following two functions facilitate this functionality.  Effectively,
 these are the C equivalent to :func:`reprlib.recursive_repr`.
 
 .. c:function:: int Py_ReprEnter(PyObject *object)
 
-   Called at the beginning of the :attr:`tp_repr` implementation to
+   Called at the beginning of the :c:member:`~PyTypeObject.tp_repr` implementation to
    detect cycles.
 
    If the object has already been processed, the function returns a
-   positive integer.  In that case the :attr:`tp_repr` implementation
+   positive integer.  In that case the :c:member:`~PyTypeObject.tp_repr` implementation
    should return a string object indicating a cycle.  As examples,
    :class:`dict` objects return ``{...}`` and :class:`list` objects
    return ``[...]``.
 
    The function will return a negative integer if the recursion limit
-   is reached.  In that case the :attr:`tp_repr` implementation should
+   is reached.  In that case the :c:member:`~PyTypeObject.tp_repr` implementation should
    typically return ``NULL``.
 
-   Otherwise, the function returns zero and the :attr:`tp_repr`
+   Otherwise, the function returns zero and the :c:member:`~PyTypeObject.tp_repr`
    implementation can continue normally.
 
 .. c:function:: void Py_ReprLeave(PyObject *object)

Doc/c-api/gcsupport.rst

 or strings), do not need to provide any explicit support for garbage
 collection.
 
-To create a container type, the :attr:`tp_flags` field of the type object must
+To create a container type, the :c:member:`~PyTypeObject.tp_flags` field of the type object must
 include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
-:attr:`tp_traverse` handler.  If instances of the type are mutable, a
-:attr:`tp_clear` implementation must also be provided.
+:c:member:`~PyTypeObject.tp_traverse` handler.  If instances of the type are mutable, a
+:c:member:`~PyTypeObject.tp_clear` implementation must also be provided.
 
 
 .. data:: Py_TPFLAGS_HAVE_GC
    Adds the object *op* to the set of container objects tracked by the
    collector.  The collector can run at unexpected times so objects must be
    valid while being tracked.  This should be called once all the fields
-   followed by the :attr:`tp_traverse` handler become valid, usually near the
+   followed by the :c:member:`~PyTypeObject.tp_traverse` handler become valid, usually near the
    end of the constructor.
 
 
    Remove the object *op* from the set of container objects tracked by the
    collector.  Note that :c:func:`PyObject_GC_Track` can be called again on
    this object to add it back to the set of tracked objects.  The deallocator
-   (:attr:`tp_dealloc` handler) should call this for the object before any of
-   the fields used by the :attr:`tp_traverse` handler become invalid.
+   (:c:member:`~PyTypeObject.tp_dealloc` handler) should call this for the object before any of
+   the fields used by the :c:member:`~PyTypeObject.tp_traverse` handler become invalid.
 
 
 .. c:function:: void _PyObject_GC_UNTRACK(PyObject *op)
    A macro version of :c:func:`PyObject_GC_UnTrack`.  It should not be used for
    extension modules.
 
-The :attr:`tp_traverse` handler accepts a function parameter of this type:
+The :c:member:`~PyTypeObject.tp_traverse` handler accepts a function parameter of this type:
 
 
 .. c:type:: int (*visitproc)(PyObject *object, void *arg)
 
-   Type of the visitor function passed to the :attr:`tp_traverse` handler.
+   Type of the visitor function passed to the :c:member:`~PyTypeObject.tp_traverse` handler.
    The function should be called with an object to traverse as *object* and
-   the third parameter to the :attr:`tp_traverse` handler as *arg*.  The
+   the third parameter to the :c:member:`~PyTypeObject.tp_traverse` handler as *arg*.  The
    Python core uses several visitor functions to implement cyclic garbage
    detection; it's not expected that users will need to write their own
    visitor functions.
 
-The :attr:`tp_traverse` handler must have the following type:
+The :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
 
 
 .. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
    object argument.  If *visit* returns a non-zero value that value should be
    returned immediately.
 
-To simplify writing :attr:`tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
-provided.  In order to use this macro, the :attr:`tp_traverse` implementation
+To simplify writing :c:member:`~PyTypeObject.tp_traverse` handlers, a :c:func:`Py_VISIT` macro is
+provided.  In order to use this macro, the :c:member:`~PyTypeObject.tp_traverse` implementation
 must name its arguments exactly *visit* and *arg*:
 
 
 .. c:function:: void Py_VISIT(PyObject *o)
 
    Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns
-   a non-zero value, then return it.  Using this macro, :attr:`tp_traverse`
+   a non-zero value, then return it.  Using this macro, :c:member:`~PyTypeObject.tp_traverse`
    handlers look like::
 
       static int
           return 0;
       }
 
-The :attr:`tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
+The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
 if the object is immutable.
 
 

Doc/c-api/index.rst

    memory.rst
    objimpl.rst
    stable.rst
+   apiabiversion.rst

Doc/c-api/init.rst

    made on the main thread.  This is mainly a helper/diagnostic function.
 
 
+.. c:function:: int PyGILState_Check()
+
+   Return 1 if the current thread is holding the GIL and 0 otherwise.
+   This function can be called from any thread at any time.
+   Only if it has had its Python thread state initialized and currently is
+   holding the GIL will it return 1.
+   This is mainly a helper/diagnostic function.  It can be useful
+   for example in callback contexts or memory allocation functions when
+   knowing that the GIL is locked can allow the caller to perform sensitive
+   actions or otherwise behave differently.
+
+   .. versionadded:: 3.4
+
+
 The following macros are normally used without a trailing semicolon; look for
 example usage in the Python source distribution.
 

Doc/c-api/intro.rst

    t = PyTuple_New(3);
    PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
    PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
-   PyTuple_SetItem(t, 2, PyString_FromString("three"));
+   PyTuple_SetItem(t, 2, PyUnicode_FromString("three"));
 
 Here, :c:func:`PyLong_FromLong` returns a new reference which is immediately
 stolen by :c:func:`PyTuple_SetItem`.  When you want to keep using an object
 .. index:: single: sum_sequence()
 
 A simple example of detecting exceptions and passing them on is shown in the
-:c:func:`sum_sequence` example above.  It so happens that that example doesn't
+:c:func:`sum_sequence` example above.  It so happens that this example doesn't
 need to clean up any owned references when it detects an error.  The following
 example function shows some error cleanup.  First, to remind you why you like
 Python, we show the equivalent Python code::

Doc/c-api/long.rst

 
 .. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
 
-   Return a C :c:type:`size_t` representation of of *pylong*.  *pylong* must be
+   Return a C :c:type:`size_t` representation of *pylong*.  *pylong* must be
    an instance of :c:type:`PyLongObject`.
 
    Raise :exc:`OverflowError` if the value of *pylong* is out of range for a
    .. index::
       single: OverflowError (built-in exception)
 
-   Return a C :c:type:`unsigned PY_LONG_LONG` representation of of *pylong*.
+   Return a C :c:type:`unsigned PY_LONG_LONG` representation of *pylong*.
    *pylong* must be an instance of :c:type:`PyLongObject`.
 
    Raise :exc:`OverflowError` if the value of *pylong* is out of range for an

Doc/c-api/memory.rst

    if (buf == NULL)
        return PyErr_NoMemory();
    ...Do some I/O operation involving buf...
-   res = PyString_FromString(buf);
+   res = PyBytes_FromString(buf);
    free(buf); /* malloc'ed */
    return res;
 
 for the I/O buffer escapes completely the Python memory manager.
 
 
+Raw Memory Interface
+====================
+
+The following function sets are wrappers to the system allocator. These
+functions are thread-safe, the :term:`GIL <global interpreter lock>` does not
+need to be held.
+
+The default raw memory block allocator uses the following functions:
+:c:func:`malloc`, :c:func:`realloc` and :c:func:`free`; call ``malloc(1)`` when
+requesting zero bytes.
+
+.. versionadded:: 3.4
+
+.. c:function:: void* PyMem_RawMalloc(size_t n)
+
+   Allocates *n* bytes and returns a pointer of type :c:type:`void\*` to the
+   allocated memory, or *NULL* if the request fails. Requesting zero bytes
+   returns a distinct non-*NULL* pointer if possible, as if
+   ``PyMem_RawMalloc(1)`` had been called instead. The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: void* PyMem_RawRealloc(void *p, size_t n)
+
+   Resizes the memory block pointed to by *p* to *n* bytes. The contents will
+   be unchanged to the minimum of the old and the new sizes. If *p* is *NULL*,
+   the call is equivalent to ``PyMem_RawMalloc(n)``; else if *n* is equal to
+   zero, the memory block is resized but is not freed, and the returned pointer
+   is non-*NULL*. Unless *p* is *NULL*, it must have been returned by a
+   previous call to :c:func:`PyMem_RawMalloc` or :c:func:`PyMem_RawRealloc`. If
+   the request fails, :c:func:`PyMem_RawRealloc` returns *NULL* and *p* remains
+   a valid pointer to the previous memory area.
+
+
+.. c:function:: void PyMem_RawFree(void *p)
+
+   Frees the memory block pointed to by *p*, which must have been returned by a
+   previous call to :c:func:`PyMem_RawMalloc` or :c:func:`PyMem_RawRealloc`.
+   Otherwise, or if ``PyMem_Free(p)`` has been called before, undefined
+   behavior occurs. If *p* is *NULL*, no operation is performed.
+
+
 .. _memoryinterface:
 
 Memory Interface
 
 The following function sets, modeled after the ANSI C standard, but specifying
 behavior when requesting zero bytes, are available for allocating and releasing
-memory from the Python heap:
+memory from the Python heap.
 
+The default memory block allocator uses the following functions:
+:c:func:`malloc`, :c:func:`realloc` and :c:func:`free`; call ``malloc(1)`` when
+requesting zero bytes.
+
+.. warning::
+
+   The :term:`GIL <global interpreter lock>` must be held when using these
+   functions.
 
 .. c:function:: void* PyMem_Malloc(size_t n)
 
 :c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`.
 
 
+Customize Memory Allocators
+===========================
+
+.. versionadded:: 3.4
+
+.. c:type:: PyMemAllocator
+
+   Structure used to describe a memory block allocator. The structure has
+   four fields:
+
+   +----------------------------------------------------------+---------------------------------------+
+   | Field                                                    | Meaning                               |
+   +==========================================================+=======================================+
+   | ``void *ctx``                                            | user context passed as first argument |
+   +----------------------------------------------------------+---------------------------------------+
+   | ``void* malloc(void *ctx, size_t size)``                 | allocate a memory block               |
+   +----------------------------------------------------------+---------------------------------------+
+   | ``void* realloc(void *ctx, void *ptr, size_t new_size)`` | allocate or resize a memory block     |
+   +----------------------------------------------------------+---------------------------------------+
+   | ``void free(void *ctx, void *ptr)``                      | free a memory block                   |
+   +----------------------------------------------------------+---------------------------------------+
+
+.. c:type:: PyMemAllocatorDomain
+
+   Enum used to identify an allocator domain. Domains:
+
+   * :c:data:`PYMEM_DOMAIN_RAW`: functions :c:func:`PyMem_RawMalloc`,
+     :c:func:`PyMem_RawRealloc` and :c:func:`PyMem_RawFree`
+   * :c:data:`PYMEM_DOMAIN_MEM`: functions :c:func:`PyMem_Malloc`,
+     :c:func:`PyMem_Realloc` and :c:func:`PyMem_Free`
+   * :c:data:`PYMEM_DOMAIN_OBJ`: functions :c:func:`PyObject_Malloc`,
+     :c:func:`PyObject_Realloc` and :c:func:`PyObject_Free`
+
+
+.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator)
+
+   Get the memory block allocator of the specified domain.
+
+
+.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocator *allocator)
+
+   Set the memory block allocator of the specified domain.
+
+   The new allocator must return a distinct non-NULL pointer when requesting
+   zero bytes.
+
+   For the :c:data:`PYMEM_DOMAIN_RAW` domain, the allocator must be
+   thread-safe: the :term:`GIL <global interpreter lock>` is not held when the
+   allocator is called.
+
+   If the new allocator is not a hook (does not call the previous allocator),
+   the :c:func:`PyMem_SetupDebugHooks` function must be called to reinstall the
+   debug hooks on top on the new allocator.
+
+
+.. c:function:: void PyMem_SetupDebugHooks(void)
+
+   Setup hooks to detect bugs in the following Python memory allocator
+   functions:
+
+   - :c:func:`PyMem_RawMalloc`, :c:func:`PyMem_RawRealloc`,
+     :c:func:`PyMem_RawFree`
+   - :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc`, :c:func:`PyMem_Free`
+   - :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc`,
+     :c:func:`PyObject_Free`
+
+   Newly allocated memory is filled with the byte ``0xCB``, freed memory is
+   filled with the byte ``0xDB``. Additionnal checks:
+
+   - detect API violations, ex: :c:func:`PyObject_Free` called on a buffer
+     allocated by :c:func:`PyMem_Malloc`
+   - detect write before the start of the buffer (buffer underflow)
+   - detect write after the end of the buffer (buffer overflow)
+
+   The function does nothing if Python is not compiled is debug mode.
+
+
+Customize PyObject Arena Allocator
+==================================
+
+Python has a *pymalloc* allocator for allocations smaller than 512 bytes. This
+allocator is optimized for small objects with a short lifetime. It uses memory
+mappings called "arenas" with a fixed size of 256 KB. It falls back to
+:c:func:`PyMem_Malloc` and :c:func:`PyMem_Realloc` for allocations larger than
+512 bytes.  *pymalloc* is the default allocator used by
+:c:func:`PyObject_Malloc`.
+
+The default arena allocator uses the following functions:
+
+* :c:func:`VirtualAlloc` and :c:func:`VirtualFree` on Windows,
+* :c:func:`mmap` and :c:func:`munmap` if available,
+* :c:func:`malloc` and :c:func:`free` otherwise.
+
+.. versionadded:: 3.4
+
+.. c:type:: PyObjectArenaAllocator
+
+   Structure used to describe an arena allocator. The structure has
+   three fields:
+
+   +--------------------------------------------------+---------------------------------------+
+   | Field                                            | Meaning                               |
+   +==================================================+=======================================+
+   | ``void *ctx``                                    | user context passed as first argument |
+   +--------------------------------------------------+---------------------------------------+
+   | ``void* alloc(void *ctx, size_t size)``          | allocate an arena of size bytes       |
+   +--------------------------------------------------+---------------------------------------+
+   | ``void free(void *ctx, size_t size, void *ptr)`` | free an arena                         |
+   +--------------------------------------------------+---------------------------------------+
+
+.. c:function:: PyObject_GetArenaAllocator(PyObjectArenaAllocator *allocator)
+
+   Get the arena allocator.
+
+.. c:function:: PyObject_SetArenaAllocator(PyObjectArenaAllocator *allocator)
+
+   Set the arena allocator.
+
+
 .. _memoryexamples:
 
 Examples
    if (buf == NULL)
        return PyErr_NoMemory();
    /* ...Do some I/O operation involving buf... */
-   res = PyString_FromString(buf);
+   res = PyBytes_FromString(buf);
    PyMem_Free(buf); /* allocated with PyMem_Malloc */
    return res;
 
    if (buf == NULL)
        return PyErr_NoMemory();
    /* ...Do some I/O operation involving buf... */
-   res = PyString_FromString(buf);
+   res = PyBytes_FromString(buf);
    PyMem_Del(buf); /* allocated with PyMem_New */
    return res;
 

Doc/c-api/module.rst

       single: __name__ (module attribute)
       single: __doc__ (module attribute)
       single: __file__ (module attribute)
+      single: __package__ (module attribute)
+      single: __loader__ (module attribute)
 
    Return a new module object with the :attr:`__name__` attribute set to *name*.
-   Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in;
-   the caller is responsible for providing a :attr:`__file__` attribute.
+   The module's :attr:`__name__`, :attr:`__doc__`, :attr:`__package__`, and
+   :attr:`__loader__` attributes are filled in (all but :attr:`__name__` are set
+   to ``None``); the caller is responsible for providing a :attr:`__file__`
+   attribute.
 
    .. versionadded:: 3.3
 
+   .. versionchanged:: 3.4
+      :attr:`__package__` and :attr:`__loader__` are set to ``None``.
+
 
 .. c:function:: PyObject* PyModule_New(const char *name)
 
    :c:func:`PyState_AddModule` beforehand. In case the corresponding module object is not
    found or has not been attached to the interpreter state yet, it returns NULL.
 
-.. c:function:: int PyState_AddModule(PyModuleDef *def, PyObject *module)
+.. c:function:: int PyState_AddModule(PyObject *module, PyModuleDef *def)
 
    Attaches the module object passed to the function to the interpreter state. This allows
    the module object to be accessible via
 
    .. versionadded:: 3.3
 
-.. c:function:: int PyState_RemoveModule(PyModuleDef *def, PyObject *module)
+.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
 
    Removes the module object created from *def* from the interpreter state.
 

Doc/c-api/object.rst

    of the Python expression ``callable_object(*args)``.
 
 
-.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...)
+.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, const char *format, ...)
 
    Call a callable Python object *callable*, with a variable number of C arguments.
    The C arguments are described using a :c:func:`Py_BuildValue` style format
    pass :c:type:`PyObject \*` args, :c:func:`PyObject_CallFunctionObjArgs` is a
    faster alternative.
 
+   .. versionchanged:: 3.4
+      The type of *format* was changed from ``char *``.
 
-.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, char *format, ...)
+
+.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, const char *method, const char *format, ...)
 
    Call the method named *method* of object *o* with a variable number of C
    arguments.  The C arguments are described by a :c:func:`Py_BuildValue` format
    Note that if you only pass :c:type:`PyObject \*` args,
    :c:func:`PyObject_CallMethodObjArgs` is a faster alternative.
 
+   .. versionchanged:: 3.4
+      The types of *method* and *format* were changed from ``char *``.
+
 
 .. c:function:: PyObject* PyObject_CallFunctionObjArgs(PyObject *callable, ..., NULL)
 

Doc/c-api/stable.rst

 
 .. _stable:
 
-**********************************
-Stable Appliction Binary Interface
-**********************************
+***********************************
+Stable Application Binary Interface
+***********************************
 
 Traditionally, the C API of Python will change with every release.
 Most changes will be source-compatible, typically by only adding API,
 
 Since Python 3.2, a subset of the API has been declared to guarantee
 a stable ABI. Extension modules wishing to use this API need to define
-Py_LIMITED_API. A number of interpreter details then become hidden
+``Py_LIMITED_API``. A number of interpreter details then become hidden
 from the extension module; in return, a module is built that works
-on any 3.x version (x>=2) without recompilation. In some cases, the
-stable ABI needs to be extended with new functions. Extensions modules
-wishing to use these new APIs need to set Py_LIMITED_API to the
-PY_VERSION_HEX value of the minimum Python version they want to
-support (e.g. 0x03030000 for Python 3.3). Such modules will work
+on any 3.x version (x>=2) without recompilation.
+
+In some cases, the stable ABI needs to be extended with new functions.
+Extension modules wishing to use these new APIs need to set
+``Py_LIMITED_API`` to the ``PY_VERSION_HEX`` value (see
+:ref:`apiabiversion`) of the minimum Python version they want to
+support (e.g. ``0x03030000`` for Python 3.3). Such modules will work
 on all subsequent Python releases, but fail to load (because of
 missing symbols) on the older releases.
 

Doc/c-api/type.rst

 
 .. c:function:: long PyType_GetFlags(PyTypeObject* type)
 
-   Return the :attr:`tp_flags` member of *type*. This function is primarily
+   Return the :c:member:`~PyTypeObject.tp_flags` member of *type*. This function is primarily
    meant for use with `Py_LIMITED_API`; the individual flag bits are
    guaranteed to be stable across Python releases, but access to
-   :attr:`tp_flags` itself is not part of the limited API.
+   :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API.
 
    .. versionadded:: 3.2
 
 
 .. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
 
-   Generic handler for the :attr:`tp_alloc` slot of a type object.  Use
+   Generic handler for the :c:member:`~PyTypeObject.tp_alloc` slot of a type object.  Use
    Python's default memory allocation mechanism to allocate a new instance and
    initialize all its contents to *NULL*.
 
 .. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
 
-   Generic handler for the :attr:`tp_new` slot of a type object.  Create a
-   new instance using the type's :attr:`tp_alloc` slot.
+   Generic handler for the :c:member:`~PyTypeObject.tp_new` slot of a type object.  Create a
+   new instance using the type's :c:member:`~PyTypeObject.tp_alloc` slot.
 
 .. c:function:: int PyType_Ready(PyTypeObject *type)
 

Doc/c-api/typeobj.rst

 The type object structure extends the :c:type:`PyVarObject` structure. The
 :attr:`ob_size` field is used for dynamic types (created by  :func:`type_new`,
 usually called from a class statement). Note that :c:data:`PyType_Type` (the
-metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e.
+metatype) initializes :c:member:`~PyTypeObject.tp_itemsize`, which means that its instances (i.e.
 type objects) *must* have the :attr:`ob_size` field.
 
 
    should be just the type name.  If the module is a submodule of a package, the
    full package name is part of the full module name.  For example, a type named
    :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P`
-   should have the :attr:`tp_name` initializer ``"P.Q.M.T"``.
+   should have the :c:member:`~PyTypeObject.tp_name` initializer ``"P.Q.M.T"``.
 
    For dynamically allocated type objects, this should just be the type name, and
    the module name explicitly stored in the type dict as the value for key
    attribute, and everything after the last dot is made accessible as the
    :attr:`__name__` attribute.