python-3.6.zip added from Github

README.cosmo contains the necessary links.

third_party/python/Doc/c-api/abstract.rst

@@ -0,0 +1,26 @@
+.. highlightlang:: c
+
+.. _abstract:
+
+**********************
+Abstract Objects Layer
+**********************
+
+The functions in this chapter interact with Python objects regardless of their
+type, or with wide classes of object types (e.g. all numerical types, or all
+sequence types).  When used on object types for which they do not apply, they
+will raise a Python exception.
+
+It is not possible to use these functions on objects that are not properly
+initialized, such as a list object that has been created by :c:func:`PyList_New`,
+but whose items have not been set to some non-\ ``NULL`` value yet.
+
+.. toctree::
+
+   object.rst
+   number.rst
+   sequence.rst
+   mapping.rst
+   iter.rst
+   buffer.rst
+   objbuffer.rst

third_party/python/Doc/c-api/allocation.rst

@@ -0,0 +1,71 @@
+.. highlightlang:: c
+
+.. _allocating-objects:
+
+Allocating Objects on the Heap
+==============================
+
+
+.. c:function:: PyObject* _PyObject_New(PyTypeObject *type)
+
+
+.. c:function:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
+
+
+.. c:function:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
+
+   Initialize a newly-allocated object *op* with its type and initial
+   reference.  Returns the initialized object.  If *type* indicates that the
+   object participates in the cyclic garbage detector, it is added to the
+   detector's set of observed objects. Other fields of the object are not
+   affected.
+
+
+.. c:function:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
+
+   This does everything :c:func:`PyObject_Init` does, and also initializes the
+   length information for a variable-size object.
+
+
+.. c:function:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
+
+   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 :c:member:`~PyTypeObject.tp_basicsize` field of
+   the type object.
+
+
+.. c:function:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+
+   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 :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,
+   improving the memory management efficiency.
+
+
+.. c:function:: void PyObject_Del(PyObject *op)
+
+   Releases memory allocated to an object using :c:func:`PyObject_New` or
+   :c:func:`PyObject_NewVar`.  This is normally called from the
+   :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.
+
+
+.. c:var:: PyObject _Py_NoneStruct
+
+   Object which is visible in Python as ``None``.  This should only be accessed
+   using the :c:macro:`Py_None` macro, which evaluates to a pointer to this
+   object.
+
+
+.. seealso::
+
+   :c:func:`PyModule_Create`
+      To allocate and create extension modules.
+

third_party/python/Doc/c-api/apiabiversion.rst

@@ -0,0 +1,39 @@
+.. 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`.
+

third_party/python/Doc/c-api/arg.rst

@@ -0,0 +1,676 @@
+.. highlightlang:: c
+
+.. _arg-parsing:
+
+Parsing arguments and building values
+=====================================
+
+These functions are useful when creating your own extensions functions and
+methods.  Additional information and examples are available in
+:ref:`extending-index`.
+
+The first three of these functions described, :c:func:`PyArg_ParseTuple`,
+:c:func:`PyArg_ParseTupleAndKeywords`, and :c:func:`PyArg_Parse`, all use *format
+strings* which are used to tell the function about the expected arguments.  The
+format strings use the same syntax for each of these functions.
+
+-----------------
+Parsing arguments
+-----------------
+
+A format string consists of zero or more "format units."  A format unit
+describes one Python object; it is usually a single character or a parenthesized
+sequence of format units.  With a few exceptions, a format unit that is not a
+parenthesized sequence normally corresponds to a single address argument to
+these functions.  In the following description, the quoted form is the format
+unit; the entry in (round) parentheses is the Python object type that matches
+the format unit; and the entry in [square] brackets is the type of the C
+variable(s) whose address should be passed.
+
+Strings and buffers
+-------------------
+
+These formats allow accessing an object as a contiguous chunk of memory.
+You don't have to provide raw storage for the returned unicode or bytes
+area.
+
+In general, when a format sets a pointer to a buffer, the buffer is
+managed by the corresponding Python object, and the buffer shares
+the lifetime of this object.  You won't have to release any memory yourself.
+The only exceptions are ``es``, ``es#``, ``et`` and ``et#``.
+
+However, when a :c:type:`Py_buffer` structure gets filled, the underlying
+buffer is locked so that the caller can subsequently use the buffer even
+inside a :c:type:`Py_BEGIN_ALLOW_THREADS` block without the risk of mutable data
+being resized or destroyed.  As a result, **you have to call**
+:c:func:`PyBuffer_Release` after you have finished processing the data (or
+in any early abort case).
+
+Unless otherwise stated, buffers are not NUL-terminated.
+
+Some formats require a read-only :term:`bytes-like object`, and set a
+pointer instead of a buffer structure.  They work by checking that
+the object's :c:member:`PyBufferProcs.bf_releasebuffer` field is *NULL*,
+which disallows mutable objects such as :class:`bytearray`.
+
+.. note::
+
+   For all ``#`` variants of formats (``s#``, ``y#``, etc.), the type of
+   the length argument (int or :c:type:`Py_ssize_t`) is controlled by
+   defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including
+   :file:`Python.h`.  If the macro was defined, length is a
+   :c:type:`Py_ssize_t` rather than an :c:type:`int`. This behavior will change
+   in a future Python version to only support :c:type:`Py_ssize_t` and
+   drop :c:type:`int` support. It is best to always define :c:macro:`PY_SSIZE_T_CLEAN`.
+
+
+``s`` (:class:`str`) [const char \*]
+   Convert a Unicode object to a C pointer to a character string.
+   A pointer to an existing string is stored in the character pointer
+   variable whose address you pass.  The C string is NUL-terminated.
+   The Python string must not contain embedded null code points; if it does,
+   a :exc:`ValueError` exception is raised. Unicode objects are converted
+   to C strings using ``'utf-8'`` encoding. If this conversion fails, a
+   :exc:`UnicodeError` is raised.
+
+   .. note::
+      This format does not accept :term:`bytes-like objects
+      <bytes-like object>`.  If you want to accept
+      filesystem paths and convert them to C character strings, it is
+      preferable to use the ``O&`` format with :c:func:`PyUnicode_FSConverter`
+      as *converter*.
+
+   .. versionchanged:: 3.5
+      Previously, :exc:`TypeError` was raised when embedded null code points
+      were encountered in the Python string.
+
+``s*`` (:class:`str` or :term:`bytes-like object`) [Py_buffer]
+   This format accepts Unicode objects as well as bytes-like objects.
+   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.
+
+``s#`` (:class:`str`, read-only :term:`bytes-like object`) [const char \*, int or :c:type:`Py_ssize_t`]
+   Like ``s*``, except that it doesn't accept mutable objects.
+   The result is stored into two C variables,
+   the first one a pointer to a C string, the second one its length.
+   The string may contain embedded null bytes. Unicode objects are converted
+   to C strings using ``'utf-8'`` encoding.
+
+``z`` (:class:`str` or ``None``) [const char \*]
+   Like ``s``, but the Python object may also be ``None``, in which case the C
+   pointer is set to *NULL*.
+
+``z*`` (:class:`str`, :term:`bytes-like object` or ``None``) [Py_buffer]
+   Like ``s*``, but the Python object may also be ``None``, in which case the
+   ``buf`` member of the :c:type:`Py_buffer` structure is set to *NULL*.
+
+``z#`` (:class:`str`, read-only :term:`bytes-like object` or ``None``) [const char \*, int]
+   Like ``s#``, but the Python object may also be ``None``, in which case the C
+   pointer is set to *NULL*.
+
+``y`` (read-only :term:`bytes-like object`) [const char \*]
+   This format converts a bytes-like object to a C pointer to a character
+   string; it does not accept Unicode objects.  The bytes buffer must not
+   contain embedded null bytes; if it does, a :exc:`ValueError`
+   exception is raised.
+
+   .. versionchanged:: 3.5
+      Previously, :exc:`TypeError` was raised when embedded null bytes were
+      encountered in the bytes buffer.
+
+``y*`` (:term:`bytes-like object`) [Py_buffer]
+   This variant on ``s*`` doesn't accept Unicode objects, only
+   bytes-like objects.  **This is the recommended way to accept
+   binary data.**
+
+``y#`` (read-only :term:`bytes-like object`) [const char \*, int]
+   This variant on ``s#`` doesn't accept Unicode objects, only bytes-like
+   objects.
+
+``S`` (:class:`bytes`) [PyBytesObject \*]
+   Requires that the Python object is a :class:`bytes` object, without
+   attempting any conversion.  Raises :exc:`TypeError` if the object is not
+   a bytes object.  The C variable may also be declared as :c:type:`PyObject\*`.
+
+``Y`` (:class:`bytearray`) [PyByteArrayObject \*]
+   Requires that the Python object is a :class:`bytearray` object, without
+   attempting any conversion.  Raises :exc:`TypeError` if the object is not
+   a :class:`bytearray` object. The C variable may also be declared as :c:type:`PyObject\*`.
+
+``u`` (:class:`str`) [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 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``u#`` (:class:`str`) [Py_UNICODE \*, int]
+   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 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``Z`` (:class:`str` or ``None``) [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 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyUnicode_AsWideCharString`.
+
+``Z#`` (:class:`str` or ``None``) [Py_UNICODE \*, int]
+   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 4.0
+      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
+   object.  The C variable may also be declared as :c:type:`PyObject\*`.
+
+``w*`` (read-write :term:`bytes-like object`) [Py_buffer]
+   This format accepts any object which implements the read-write buffer
+   interface. It fills a :c:type:`Py_buffer` structure provided by the caller.
+   The buffer may contain embedded null bytes. The caller have to call
+   :c:func:`PyBuffer_Release` when it is done with the buffer.
+
+``es`` (:class:`str`) [const char \*encoding, char \*\*buffer]
+   This variant on ``s`` is used for encoding Unicode into a character buffer.
+   It only works for encoded data without embedded NUL bytes.
+
+   This format requires two arguments.  The first is only used as input, and
+   must be a :c:type:`const char\*` which points to the name of an encoding as a
+   NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
+   An exception is raised if the named encoding is not known to Python.  The
+   second argument must be a :c:type:`char\*\*`; the value of the pointer it
+   references will be set to a buffer with the contents of the argument text.
+   The text will be encoded in the encoding specified by the first argument.
+
+   :c:func:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the
+   encoded data into this buffer and adjust *\*buffer* to reference the newly
+   allocated storage.  The caller is responsible for calling :c:func:`PyMem_Free` to
+   free the allocated buffer after use.
+
+``et`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer]
+   Same as ``es`` except that byte string objects are passed through without
+   recoding them.  Instead, the implementation assumes that the byte string object uses
+   the encoding passed in as parameter.
+
+``es#`` (:class:`str`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
+   This variant on ``s#`` is used for encoding Unicode into a character buffer.
+   Unlike the ``es`` format, this variant allows input data which contains NUL
+   characters.
+
+   It requires three arguments.  The first is only used as input, and must be a
+   :c:type:`const char\*` which points to the name of an encoding as a
+   NUL-terminated string, or *NULL*, in which case ``'utf-8'`` encoding is used.
+   An exception is raised if the named encoding is not known to Python.  The
+   second argument must be a :c:type:`char\*\*`; the value of the pointer it
+   references will be set to a buffer with the contents of the argument text.
+   The text will be encoded in the encoding specified by the first argument.
+   The third argument must be a pointer to an integer; the referenced integer
+   will be set to the number of bytes in the output buffer.
+
+   There are two modes of operation:
+
+   If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of
+   the needed size, copy the encoded data into this buffer and set *\*buffer* to
+   reference the newly allocated storage.  The caller is responsible for calling
+   :c:func:`PyMem_Free` to free the allocated buffer after usage.
+
+   If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
+   :c:func:`PyArg_ParseTuple` will use this location as the buffer and interpret the
+   initial value of *\*buffer_length* as the buffer size.  It will then copy the
+   encoded data into the buffer and NUL-terminate it.  If the buffer is not large
+   enough, a :exc:`ValueError` will be set.
+
+   In both cases, *\*buffer_length* is set to the length of the encoded data
+   without the trailing NUL byte.
+
+``et#`` (:class:`str`, :class:`bytes` or :class:`bytearray`) [const char \*encoding, char \*\*buffer, int \*buffer_length]
+   Same as ``es#`` except that byte string objects are passed through without recoding
+   them. Instead, the implementation assumes that the byte string object uses the
+   encoding passed in as parameter.
+
+Numbers
+-------
+
+``b`` (:class:`int`) [unsigned char]
+   Convert a nonnegative Python integer to an unsigned tiny int, stored in a C
+   :c:type:`unsigned char`.
+
+``B`` (:class:`int`) [unsigned char]
+   Convert a Python integer to a tiny int without overflow checking, stored in a C
+   :c:type:`unsigned char`.
+
+``h`` (:class:`int`) [short int]
+   Convert a Python integer to a C :c:type:`short int`.
+
+``H`` (:class:`int`) [unsigned short int]
+   Convert a Python integer to a C :c:type:`unsigned short int`, without overflow
+   checking.
+
+``i`` (:class:`int`) [int]
+   Convert a Python integer to a plain C :c:type:`int`.
+
+``I`` (:class:`int`) [unsigned int]
+   Convert a Python integer to a C :c:type:`unsigned int`, without overflow
+   checking.
+
+``l`` (:class:`int`) [long int]
+   Convert a Python integer to a C :c:type:`long int`.
+
+``k`` (:class:`int`) [unsigned long]
+   Convert a Python integer to a C :c:type:`unsigned long` without
+   overflow checking.
+
+``L`` (:class:`int`) [long long]
+   Convert a Python integer to a C :c:type:`long long`.
+
+``K`` (:class:`int`) [unsigned long long]
+   Convert a Python integer to a C :c:type:`unsigned long long`
+   without overflow checking.
+
+``n`` (:class:`int`) [Py_ssize_t]
+   Convert a Python integer to a C :c:type:`Py_ssize_t`.
+
+``c`` (:class:`bytes` or :class:`bytearray` of length 1) [char]
+   Convert a Python byte, represented as a :class:`bytes` or
+   :class:`bytearray` object of length 1, to a C :c:type:`char`.
+
+   .. versionchanged:: 3.3
+      Allow :class:`bytearray` objects.
+
+``C`` (:class:`str` of length 1) [int]
+   Convert a Python character, represented as a :class:`str` object of
+   length 1, to a C :c:type:`int`.
+
+``f`` (:class:`float`) [float]
+   Convert a Python floating point number to a C :c:type:`float`.
+
+``d`` (:class:`float`) [double]
+   Convert a Python floating point number to a C :c:type:`double`.
+
+``D`` (:class:`complex`) [Py_complex]
+   Convert a Python complex number to a C :c:type:`Py_complex` structure.
+
+Other objects
+-------------
+
+``O`` (object) [PyObject \*]
+   Store a Python object (without any conversion) in a C object pointer.  The C
+   program thus receives the actual object that was passed.  The object's reference
+   count is not increased.  The pointer stored is not *NULL*.
+
+``O!`` (object) [*typeobject*, PyObject \*]
+   Store a Python object in a C object pointer.  This is similar to ``O``, but
+   takes two C arguments: the first is the address of a Python type object, the
+   second is the address of the C variable (of type :c:type:`PyObject\*`) into which
+   the object pointer is stored.  If the Python object does not have the required
+   type, :exc:`TypeError` is raised.
+
+.. _o_ampersand:
+
+``O&`` (object) [*converter*, *anything*]
+   Convert a Python object to a C variable through a *converter* function.  This
+   takes two arguments: the first is a function, the second is the address of a C
+   variable (of arbitrary type), converted to :c:type:`void \*`.  The *converter*
+   function in turn is called as follows::
+
+      status = converter(object, address);
+
+   where *object* is the Python object to be converted and *address* is the
+   :c:type:`void\*` argument that was passed to the :c:func:`PyArg_Parse\*` function.
+   The returned *status* should be ``1`` for a successful conversion and ``0`` if
+   the conversion has failed.  When the conversion fails, the *converter* function
+   should raise an exception and leave the content of *address* unmodified.
+
+   If the *converter* returns ``Py_CLEANUP_SUPPORTED``, it may get called a
+   second time if the argument parsing eventually fails, giving the converter a
+   chance to release any memory that it had already allocated. In this second
+   call, the *object* parameter will be NULL; *address* will have the same value
+   as in the original call.
+
+   .. versionchanged:: 3.1
+      ``Py_CLEANUP_SUPPORTED`` was added.
+
+``p`` (:class:`bool`) [int]
+   Tests the value passed in for truth (a boolean **p**\ redicate) and converts
+   the result to its equivalent C true/false integer value.
+   Sets the int to ``1`` if the expression was true and ``0`` if it was false.
+   This accepts any valid Python value.  See :ref:`truth` for more
+   information about how Python tests values for truth.
+
+   .. versionadded:: 3.3
+
+``(items)`` (:class:`tuple`) [*matching-items*]
+   The object must be a Python sequence whose length is the number of format units
+   in *items*.  The C arguments must correspond to the individual format units in
+   *items*.  Format units for sequences may be nested.
+
+It is possible to pass "long" integers (integers whose value exceeds the
+platform's :const:`LONG_MAX`) however no proper range checking is done --- the
+most significant bits are silently truncated when the receiving field is too
+small to receive the value (actually, the semantics are inherited from downcasts
+in C --- your mileage may vary).
+
+A few other characters have a meaning in a format string.  These may not occur
+inside nested parentheses.  They are:
+
+``|``
+   Indicates that the remaining arguments in the Python argument list are optional.
+   The C variables corresponding to optional arguments should be initialized to
+   their default value --- when an optional argument is not specified,
+   :c:func:`PyArg_ParseTuple` does not touch the contents of the corresponding C
+   variable(s).
+
+``$``
+   :c:func:`PyArg_ParseTupleAndKeywords` only:
+   Indicates that the remaining arguments in the Python argument list are
+   keyword-only.  Currently, all keyword-only arguments must also be optional
+   arguments, so ``|`` must always be specified before ``$`` in the format
+   string.
+
+   .. versionadded:: 3.3
+
+``:``
+   The list of format units ends here; the string after the colon is used as the
+   function name in error messages (the "associated value" of the exception that
+   :c:func:`PyArg_ParseTuple` raises).
+
+``;``
+   The list of format units ends here; the string after the semicolon is used as
+   the error message *instead* of the default error message.  ``:`` and ``;``
+   mutually exclude each other.
+
+Note that any Python object references which are provided to the caller are
+*borrowed* references; do not decrement their reference count!
+
+Additional arguments passed to these functions must be addresses of variables
+whose type is determined by the format string; these are used to store values
+from the input tuple.  There are a few cases, as described in the list of format
+units above, where these parameters are used as input values; they should match
+what is specified for the corresponding format unit in that case.
+
+For the conversion to succeed, the *arg* object must match the format
+and the format must be exhausted.  On success, the
+:c:func:`PyArg_Parse\*` functions return true, otherwise they return
+false and raise an appropriate exception. When the
+:c:func:`PyArg_Parse\*` functions fail due to conversion failure in one
+of the format units, the variables at the addresses corresponding to that
+and the following format units are left untouched.
+
+API Functions
+-------------
+
+.. c:function:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)
+
+   Parse the parameters of a function that takes only positional parameters into
+   local variables.  Returns true on success; on failure, it returns false and
+   raises the appropriate exception.
+
+
+.. c:function:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
+
+   Identical to :c:func:`PyArg_ParseTuple`, except that it accepts a va_list rather
+   than a variable number of arguments.
+
+
+.. c:function:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)
+
+   Parse the parameters of a function that takes both positional and keyword
+   parameters into local variables.  The *keywords* argument is a
+   *NULL*-terminated array of keyword parameter names.  Empty names denote
+   :ref:`positional-only parameters <positional-only_parameter>`.
+   Returns true on success; on failure, it returns false and raises the
+   appropriate exception.
+
+   .. versionchanged:: 3.6
+      Added support for :ref:`positional-only parameters
+      <positional-only_parameter>`.
+
+
+.. c:function:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
+
+   Identical to :c:func:`PyArg_ParseTupleAndKeywords`, except that it accepts a
+   va_list rather than a variable number of arguments.
+
+
+.. c:function:: int PyArg_ValidateKeywordArguments(PyObject *)
+
+   Ensure that the keys in the keywords argument dictionary are strings.  This
+   is only needed if :c:func:`PyArg_ParseTupleAndKeywords` is not used, since the
+   latter already does this check.
+
+   .. versionadded:: 3.2
+
+
+.. XXX deprecated, will be removed
+.. c:function:: int PyArg_Parse(PyObject *args, const char *format, ...)
+
+   Function used to deconstruct the argument lists of "old-style" functions ---
+   these are functions which use the :const:`METH_OLDARGS` parameter parsing
+   method, which has been removed in Python 3.  This is not recommended for use
+   in parameter parsing in new code, and most code in the standard interpreter
+   has been modified to no longer use this for that purpose.  It does remain a
+   convenient way to decompose other tuples, however, and may continue to be
+   used for that purpose.
+
+
+.. c:function:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)
+
+   A simpler form of parameter retrieval which does not use a format string to
+   specify the types of the arguments.  Functions which use this method to retrieve
+   their parameters should be declared as :const:`METH_VARARGS` in function or
+   method tables.  The tuple containing the actual parameters should be passed as
+   *args*; it must actually be a tuple.  The length of the tuple must be at least
+   *min* and no more than *max*; *min* and *max* may be equal.  Additional
+   arguments must be passed to the function, each of which should be a pointer to a
+   :c:type:`PyObject\*` variable; these will be filled in with the values from
+   *args*; they will contain borrowed references.  The variables which correspond
+   to optional parameters not given by *args* will not be filled in; these should
+   be initialized by the caller. This function returns true on success and false if
+   *args* is not a tuple or contains the wrong number of elements; an exception
+   will be set if there was a failure.
+
+   This is an example of the use of this function, taken from the sources for the
+   :mod:`_weakref` helper module for weak references::
+
+      static PyObject *
+      weakref_ref(PyObject *self, PyObject *args)
+      {
+          PyObject *object;
+          PyObject *callback = NULL;
+          PyObject *result = NULL;
+
+          if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {
+              result = PyWeakref_NewRef(object, callback);
+          }
+          return result;
+      }
+
+   The call to :c:func:`PyArg_UnpackTuple` in this example is entirely equivalent to
+   this call to :c:func:`PyArg_ParseTuple`::
+
+      PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
+
+
+---------------
+Building values
+---------------
+
+.. c:function:: PyObject* Py_BuildValue(const char *format, ...)
+
+   Create a new value based on a format string similar to those accepted by the
+   :c:func:`PyArg_Parse\*` family of functions and a sequence of values.  Returns
+   the value or *NULL* in the case of an error; an exception will be raised if
+   *NULL* is returned.
+
+   :c:func:`Py_BuildValue` does not always build a tuple.  It builds a tuple only if
+   its format string contains two or more format units.  If the format string is
+   empty, it returns ``None``; if it contains exactly one format unit, it returns
+   whatever object is described by that format unit.  To force it to return a tuple
+   of size 0 or one, parenthesize the format string.
+
+   When memory buffers are passed as parameters to supply data to build objects, as
+   for the ``s`` and ``s#`` formats, the required data is copied.  Buffers provided
+   by the caller are never referenced by the objects created by
+   :c:func:`Py_BuildValue`.  In other words, if your code invokes :c:func:`malloc`
+   and passes the allocated memory to :c:func:`Py_BuildValue`, your code is
+   responsible for calling :c:func:`free` for that memory once
+   :c:func:`Py_BuildValue` returns.
+
+   In the following description, the quoted form is the format unit; the entry in
+   (round) parentheses is the Python object type that the format unit will return;
+   and the entry in [square] brackets is the type of the C value(s) to be passed.
+
+   The characters space, tab, colon and comma are ignored in format strings (but
+   not within format units such as ``s#``).  This can be used to make long format
+   strings a tad more readable.
+
+   ``s`` (:class:`str` or ``None``) [char \*]
+      Convert a null-terminated C string to a Python :class:`str` object using ``'utf-8'``
+      encoding. If the C string pointer is *NULL*, ``None`` is used.
+
+   ``s#`` (:class:`str` or ``None``) [char \*, int]
+      Convert a C string and its length to a Python :class:`str` object using ``'utf-8'``
+      encoding. If the C string pointer is *NULL*, the length is ignored and
+      ``None`` is returned.
+
+   ``y`` (:class:`bytes`) [char \*]
+      This converts a C string to a Python :class:`bytes` object.  If the C
+      string pointer is *NULL*, ``None`` is returned.
+
+   ``y#`` (:class:`bytes`) [char \*, int]
+      This converts a C string and its lengths to a Python object.  If the C
+      string pointer is *NULL*, ``None`` is returned.
+
+   ``z`` (:class:`str` or ``None``) [char \*]
+      Same as ``s``.
+
+   ``z#`` (:class:`str` or ``None``) [char \*, int]
+      Same as ``s#``.
+
+   ``u`` (:class:`str`) [wchar_t \*]
+      Convert a null-terminated :c:type:`wchar_t` buffer of Unicode (UTF-16 or UCS-4)
+      data to a Python Unicode object.  If the Unicode buffer pointer is *NULL*,
+      ``None`` is returned.
+
+   ``u#`` (:class:`str`) [wchar_t \*, int]
+      Convert a Unicode (UTF-16 or UCS-4) data buffer and its length to a Python
+      Unicode object.   If the Unicode buffer pointer is *NULL*, the length is ignored
+      and ``None`` is returned.
+
+   ``U`` (:class:`str` or ``None``) [char \*]
+      Same as ``s``.
+
+   ``U#`` (:class:`str` or ``None``) [char \*, int]
+      Same as ``s#``.
+
+   ``i`` (:class:`int`) [int]
+      Convert a plain C :c:type:`int` to a Python integer object.
+
+   ``b`` (:class:`int`) [char]
+      Convert a plain C :c:type:`char` to a Python integer object.
+
+   ``h`` (:class:`int`) [short int]
+      Convert a plain C :c:type:`short int` to a Python integer object.
+
+   ``l`` (:class:`int`) [long int]
+      Convert a C :c:type:`long int` to a Python integer object.
+
+   ``B`` (:class:`int`) [unsigned char]
+      Convert a C :c:type:`unsigned char` to a Python integer object.
+
+   ``H`` (:class:`int`) [unsigned short int]
+      Convert a C :c:type:`unsigned short int` to a Python integer object.
+
+   ``I`` (:class:`int`) [unsigned int]
+      Convert a C :c:type:`unsigned int` to a Python integer object.
+
+   ``k`` (:class:`int`) [unsigned long]
+      Convert a C :c:type:`unsigned long` to a Python integer object.
+
+   ``L`` (:class:`int`) [long long]
+      Convert a C :c:type:`long long` to a Python integer object.
+
+   ``K`` (:class:`int`) [unsigned long long]
+      Convert a C :c:type:`unsigned long long` to a Python integer object.
+
+   ``n`` (:class:`int`) [Py_ssize_t]
+      Convert a C :c:type:`Py_ssize_t` to a Python integer.
+
+   ``c`` (:class:`bytes` of length 1) [char]
+      Convert a C :c:type:`int` representing a byte to a Python :class:`bytes` object of
+      length 1.
+
+   ``C`` (:class:`str` of length 1) [int]
+      Convert a C :c:type:`int` representing a character to Python :class:`str`
+      object of length 1.
+
+   ``d`` (:class:`float`) [double]
+      Convert a C :c:type:`double` to a Python floating point number.
+
+   ``f`` (:class:`float`) [float]
+      Convert a C :c:type:`float` to a Python floating point number.
+
+   ``D`` (:class:`complex`) [Py_complex \*]
+      Convert a C :c:type:`Py_complex` structure to a Python complex number.
+
+   ``O`` (object) [PyObject \*]
+      Pass a Python object untouched (except for its reference count, which is
+      incremented by one).  If the object passed in is a *NULL* pointer, it is assumed
+      that this was caused because the call producing the argument found an error and
+      set an exception. Therefore, :c:func:`Py_BuildValue` will return *NULL* but won't
+      raise an exception.  If no exception has been raised yet, :exc:`SystemError` is
+      set.
+
+   ``S`` (object) [PyObject \*]
+      Same as ``O``.
+
+   ``N`` (object) [PyObject \*]
+      Same as ``O``, except it doesn't increment the reference count on the object.
+      Useful when the object is created by a call to an object constructor in the
+      argument list.
+
+   ``O&`` (object) [*converter*, *anything*]
+      Convert *anything* to a Python object through a *converter* function.  The
+      function is called with *anything* (which should be compatible with :c:type:`void
+      \*`) as its argument and should return a "new" Python object, or *NULL* if an
+      error occurred.
+
+   ``(items)`` (:class:`tuple`) [*matching-items*]
+      Convert a sequence of C values to a Python tuple with the same number of items.
+
+   ``[items]`` (:class:`list`) [*matching-items*]
+      Convert a sequence of C values to a Python list with the same number of items.
+
+   ``{items}`` (:class:`dict`) [*matching-items*]
+      Convert a sequence of C values to a Python dictionary.  Each pair of consecutive
+      C values adds one item to the dictionary, serving as key and value,
+      respectively.
+
+   If there is an error in the format string, the :exc:`SystemError` exception is
+   set and *NULL* returned.
+
+.. c:function:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
+
+   Identical to :c:func:`Py_BuildValue`, except that it accepts a va_list
+   rather than a variable number of arguments.

third_party/python/Doc/c-api/bool.rst

@@ -0,0 +1,46 @@
+.. highlightlang:: c
+
+.. _boolobjects:
+
+Boolean Objects
+---------------
+
+Booleans in Python are implemented as a subclass of integers.  There are only
+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.
+
+
+.. c:function:: int PyBool_Check(PyObject *o)
+
+   Return true if *o* is of type :c:data:`PyBool_Type`.
+
+
+.. c:var:: PyObject* Py_False
+
+   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.  It needs to be treated
+   just like any other object with respect to reference counts.
+
+
+.. c:macro:: Py_RETURN_FALSE
+
+   Return :const:`Py_False` from a function, properly incrementing its reference
+   count.
+
+
+.. c:macro:: Py_RETURN_TRUE
+
+   Return :const:`Py_True` from a function, properly incrementing its reference
+   count.
+
+
+.. c:function:: PyObject* PyBool_FromLong(long v)
+
+   Return a new reference to :const:`Py_True` or :const:`Py_False` depending on the
+   truth value of *v*.

third_party/python/Doc/c-api/buffer.rst

@@ -0,0 +1,508 @@
+.. highlightlang:: c
+
+.. index::
+   single: buffer protocol
+   single: buffer interface; (see buffer protocol)
+   single: buffer object; (see buffer protocol)
+
+.. _bufferobjects:
+
+Buffer Protocol
+---------------
+
+.. sectionauthor:: Greg Stein <gstein@lyra.org>
+.. sectionauthor:: Benjamin Peterson
+.. sectionauthor:: Stefan Krah
+
+
+Certain objects available in Python wrap access to an underlying memory
+array or *buffer*.  Such objects include the built-in :class:`bytes` and
+:class:`bytearray`, and some extension types like :class:`array.array`.
+Third-party libraries may define their own types for special purposes, such
+as image processing or numeric analysis.
+
+While each of these types have their own semantics, they share the common
+characteristic of being backed by a possibly large memory buffer.  It is
+then desirable, in some situations, to access that buffer directly and
+without intermediate copying.
+
+Python provides such a facility at the C level in the form of the :ref:`buffer
+protocol <bufferobjects>`.  This protocol has two sides:
+
+.. index:: single: PyBufferProcs
+
+- on the producer side, a type can export a "buffer interface" which allows
+  objects of that type to expose information about their underlying buffer.
+  This interface is described in the section :ref:`buffer-structs`;
+
+- on the consumer side, several means are available to obtain a pointer to
+  the raw underlying data of an object (for example a method parameter).
+
+Simple objects such as :class:`bytes` and :class:`bytearray` expose their
+underlying buffer in byte-oriented form.  Other forms are possible; for example,
+the elements exposed by an :class:`array.array` can be multi-byte values.
+
+An example consumer of the buffer interface is the :meth:`~io.BufferedIOBase.write`
+method of file objects: any object that can export a series of bytes through
+the buffer interface can be written to a file.  While :meth:`write` only
+needs read-only access to the internal contents of the object passed to it,
+other methods such as :meth:`~io.BufferedIOBase.readinto` need write access
+to the contents of their argument.  The buffer interface allows objects to
+selectively allow or reject exporting of read-write and read-only buffers.
+
+There are two ways for a consumer of the buffer interface to acquire a buffer
+over a target object:
+
+* call :c:func:`PyObject_GetBuffer` with the right parameters;
+
+* call :c:func:`PyArg_ParseTuple` (or one of its siblings) with one of the
+  ``y*``, ``w*`` or ``s*`` :ref:`format codes <arg-parsing>`.
+
+In both cases, :c:func:`PyBuffer_Release` must be called when the buffer
+isn't needed anymore.  Failure to do so could lead to various issues such as
+resource leaks.
+
+
+.. _buffer-structure:
+
+Buffer structure
+================
+
+Buffer structures (or simply "buffers") are useful as a way to expose the
+binary data from another object to the Python programmer.  They can also be
+used as a zero-copy slicing mechanism.  Using their ability to reference a
+block of memory, it is possible to expose any data to the Python programmer
+quite easily.  The memory could be a large, constant array in a C extension,
+it could be a raw block of memory for manipulation before passing to an
+operating system library, or it could be used to pass around structured data
+in its native, in-memory format.
+
+Contrary to most data types exposed by the Python interpreter, buffers
+are not :c:type:`PyObject` pointers but rather simple C structures.  This
+allows them to be created and copied very simply.  When a generic wrapper
+around a buffer is needed, a :ref:`memoryview <memoryview-objects>` object
+can be created.
+
+For short instructions how to write an exporting object, see
+:ref:`Buffer Object Structures <buffer-structs>`. For obtaining
+a buffer, see :c:func:`PyObject_GetBuffer`.
+
+.. c:type:: Py_buffer
+
+   .. c:member:: void \*buf
+
+      A pointer to the start of the logical structure described by the buffer
+      fields. This can be any location within the underlying physical memory
+      block of the exporter. For example, with negative :c:member:`~Py_buffer.strides`
+      the value may point to the end of the memory block.
+
+      For :term:`contiguous` arrays, the value points to the beginning of
+      the memory block.
+
+   .. c:member:: void \*obj
+
+      A new reference to the exporting object. The reference is owned by
+      the consumer and automatically decremented and set to *NULL* by
+      :c:func:`PyBuffer_Release`. The field is the equivalent of the return
+      value of any standard C-API function.
+
+      As a special case, for *temporary* buffers that are wrapped by
+      :c:func:`PyMemoryView_FromBuffer` or :c:func:`PyBuffer_FillInfo`
+      this field is *NULL*. In general, exporting objects MUST NOT
+      use this scheme.
+
+   .. c:member:: Py_ssize_t len
+
+      ``product(shape) * itemsize``. For contiguous arrays, this is the length
+      of the underlying memory block. For non-contiguous arrays, it is the length
+      that the logical structure would have if it were copied to a contiguous
+      representation.
+
+      Accessing ``((char *)buf)[0] up to ((char *)buf)[len-1]`` is only valid
+      if the buffer has been obtained by a request that guarantees contiguity. In
+      most cases such a request will be :c:macro:`PyBUF_SIMPLE` or :c:macro:`PyBUF_WRITABLE`.
+
+   .. c:member:: int readonly
+
+      An indicator of whether the buffer is read-only. This field is controlled
+      by the :c:macro:`PyBUF_WRITABLE` flag.
+
+   .. c:member:: Py_ssize_t itemsize
+
+      Item size in bytes of a single element. Same as the value of :func:`struct.calcsize`
+      called on non-NULL :c:member:`~Py_buffer.format` values.
+
+      Important exception: If a consumer requests a buffer without the
+      :c:macro:`PyBUF_FORMAT` flag, :c:member:`~Py_buffer.format` will
+      be set to  *NULL*,  but :c:member:`~Py_buffer.itemsize` still has
+      the value for the original format.
+
+      If :c:member:`~Py_buffer.shape` is present, the equality
+      ``product(shape) * itemsize == len`` still holds and the consumer
+      can use :c:member:`~Py_buffer.itemsize` to navigate the buffer.
+
+      If :c:member:`~Py_buffer.shape` is *NULL* as a result of a :c:macro:`PyBUF_SIMPLE`
+      or a :c:macro:`PyBUF_WRITABLE` request, the consumer must disregard
+      :c:member:`~Py_buffer.itemsize` and assume ``itemsize == 1``.
+
+   .. c:member:: const char \*format
+
+      A *NUL* terminated string in :mod:`struct` module style syntax describing
+      the contents of a single item. If this is *NULL*, ``"B"`` (unsigned bytes)
+      is assumed.
+
+      This field is controlled by the :c:macro:`PyBUF_FORMAT` flag.
+
+   .. c:member:: int ndim
+
+      The number of dimensions the memory represents as an n-dimensional array.
+      If it is ``0``, :c:member:`~Py_buffer.buf` points to a single item representing
+      a scalar. In this case, :c:member:`~Py_buffer.shape`, :c:member:`~Py_buffer.strides`
+      and :c:member:`~Py_buffer.suboffsets` MUST be *NULL*.
+
+      The macro :c:macro:`PyBUF_MAX_NDIM` limits the maximum number of dimensions
+      to 64. Exporters MUST respect this limit, consumers of multi-dimensional
+      buffers SHOULD be able to handle up to :c:macro:`PyBUF_MAX_NDIM` dimensions.
+
+   .. c:member:: Py_ssize_t \*shape
+
+      An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
+      indicating the shape of the memory as an n-dimensional array. Note that
+      ``shape[0] * ... * shape[ndim-1] * itemsize`` MUST be equal to
+      :c:member:`~Py_buffer.len`.
+
+      Shape values are restricted to ``shape[n] >= 0``. The case
+      ``shape[n] == 0`` requires special attention. See `complex arrays`_
+      for further information.
+
+      The shape array is read-only for the consumer.
+
+   .. c:member:: Py_ssize_t \*strides
+
+      An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`
+      giving the number of bytes to skip to get to a new element in each
+      dimension.
+
+      Stride values can be any integer. For regular arrays, strides are
+      usually positive, but a consumer MUST be able to handle the case
+      ``strides[n] <= 0``. See `complex arrays`_ for further information.
+
+      The strides array is read-only for the consumer.
+
+   .. c:member:: Py_ssize_t \*suboffsets
+
+      An array of :c:type:`Py_ssize_t` of length :c:member:`~Py_buffer.ndim`.
+      If ``suboffsets[n] >= 0``, the values stored along the nth dimension are
+      pointers and the suboffset value dictates how many bytes to add to each
+      pointer after de-referencing. A suboffset value that is negative
+      indicates that no de-referencing should occur (striding in a contiguous
+      memory block).
+
+      If all suboffsets are negative (i.e. no de-referencing is needed), then
+      this field must be NULL (the default value).
+
+      This type of array representation is used by the Python Imaging Library
+      (PIL). See `complex arrays`_ for further information how to access elements
+      of such an array.
+
+      The suboffsets array is read-only for the consumer.
+
+   .. c:member:: void \*internal
+
+      This is for use internally by the exporting object. For example, this
+      might be re-cast as an integer by the exporter and used to store flags
+      about whether or not the shape, strides, and suboffsets arrays must be
+      freed when the buffer is released. The consumer MUST NOT alter this
+      value.
+
+.. _buffer-request-types:
+
+Buffer request types
+====================
+
+Buffers are usually obtained by sending a buffer request to an exporting
+object via :c:func:`PyObject_GetBuffer`. Since the complexity of the logical
+structure of the memory can vary drastically, the consumer uses the *flags*
+argument to specify the exact buffer type it can handle.
+
+All :c:data:`Py_buffer` fields are unambiguously defined by the request
+type.
+
+request-independent fields
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+The following fields are not influenced by *flags* and must always be filled in
+with the correct values: :c:member:`~Py_buffer.obj`, :c:member:`~Py_buffer.buf`,
+:c:member:`~Py_buffer.len`, :c:member:`~Py_buffer.itemsize`, :c:member:`~Py_buffer.ndim`.
+
+
+readonly, format
+~~~~~~~~~~~~~~~~
+
+   .. c:macro:: PyBUF_WRITABLE
+
+      Controls the :c:member:`~Py_buffer.readonly` field. If set, the exporter
+      MUST provide a writable buffer or else report failure. Otherwise, the
+      exporter MAY provide either a read-only or writable buffer, but the choice
+      MUST be consistent for all consumers.
+
+   .. c:macro:: PyBUF_FORMAT
+
+      Controls the :c:member:`~Py_buffer.format` field. If set, this field MUST
+      be filled in correctly. Otherwise, this field MUST be *NULL*.
+
+
+:c:macro:`PyBUF_WRITABLE` can be \|'d to any of the flags in the next section.
+Since :c:macro:`PyBUF_SIMPLE` is defined as 0, :c:macro:`PyBUF_WRITABLE`
+can be used as a stand-alone flag to request a simple writable buffer.
+
+:c:macro:`PyBUF_FORMAT` can be \|'d to any of the flags except :c:macro:`PyBUF_SIMPLE`.
+The latter already implies format ``B`` (unsigned bytes).
+
+
+shape, strides, suboffsets
+~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The flags that control the logical structure of the memory are listed
+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:macro:: PyBUF_INDIRECT |  yes  |   yes   | if needed  |
++-----------------------------+-------+---------+------------+
+| .. c:macro:: PyBUF_STRIDES  |  yes  |   yes   |    NULL    |
++-----------------------------+-------+---------+------------+
+| .. c:macro:: PyBUF_ND       |  yes  |   NULL  |    NULL    |
++-----------------------------+-------+---------+------------+
+| .. c:macro:: PyBUF_SIMPLE   |  NULL |   NULL  |    NULL    |
++-----------------------------+-------+---------+------------+
+
+
+.. index:: contiguous, C-contiguous, Fortran contiguous
+
+contiguity requests
+~~~~~~~~~~~~~~~~~~~
+
+C or Fortran :term:`contiguity <contiguous>` 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 |
++===================================+=======+=========+============+========+
+| .. c:macro:: PyBUF_C_CONTIGUOUS   |  yes  |   yes   |    NULL    |   C    |
++-----------------------------------+-------+---------+------------+--------+
+| .. c:macro:: PyBUF_F_CONTIGUOUS   |  yes  |   yes   |    NULL    |   F    |
++-----------------------------------+-------+---------+------------+--------+
+| .. c:macro:: PyBUF_ANY_CONTIGUOUS |  yes  |   yes   |    NULL    | C or F |
++-----------------------------------+-------+---------+------------+--------+
+| .. c:macro:: PyBUF_ND             |  yes  |   NULL  |    NULL    |   C    |
++-----------------------------------+-------+---------+------------+--------+
+
+
+compound requests
+~~~~~~~~~~~~~~~~~
+
+All possible requests are fully defined by some combination of the flags in
+the previous section. For convenience, the buffer protocol provides frequently
+used combinations as single flags.
+
+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 |
++===============================+=======+=========+============+========+==========+========+
+| .. c:macro:: PyBUF_FULL       |  yes  |   yes   | if needed  |   U    |     0    |  yes   |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_FULL_RO    |  yes  |   yes   | if needed  |   U    |  1 or 0  |  yes   |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_RECORDS    |  yes  |   yes   |    NULL    |   U    |     0    |  yes   |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_RECORDS_RO |  yes  |   yes   |    NULL    |   U    |  1 or 0  |  yes   |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_STRIDED    |  yes  |   yes   |    NULL    |   U    |     0    |  NULL  |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_STRIDED_RO |  yes  |   yes   |    NULL    |   U    |  1 or 0  |  NULL  |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_CONTIG     |  yes  |   NULL  |    NULL    |   C    |     0    |  NULL  |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+| .. c:macro:: PyBUF_CONTIG_RO  |  yes  |   NULL  |    NULL    |   C    |  1 or 0  |  NULL  |
++-------------------------------+-------+---------+------------+--------+----------+--------+
+
+
+Complex arrays
+==============
+
+NumPy-style: shape and strides
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The logical structure of NumPy-style arrays is defined by :c:member:`~Py_buffer.itemsize`,
+:c:member:`~Py_buffer.ndim`, :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides`.
+
+If ``ndim == 0``, the memory location pointed to by :c:member:`~Py_buffer.buf` is
+interpreted as a scalar of size :c:member:`~Py_buffer.itemsize`. In that case,
+both :c:member:`~Py_buffer.shape` and :c:member:`~Py_buffer.strides` are *NULL*.
+
+If :c:member:`~Py_buffer.strides` is *NULL*, the array is interpreted as
+a standard n-dimensional C-array. Otherwise, the consumer must access an
+n-dimensional array as follows:
+
+   ``ptr = (char *)buf + indices[0] * strides[0] + ... + indices[n-1] * strides[n-1]``
+   ``item = *((typeof(item) *)ptr);``
+
+
+As noted above, :c:member:`~Py_buffer.buf` can point to any location within
+the actual memory block. An exporter can check the validity of a buffer with
+this function:
+
+.. code-block:: python
+
+   def verify_structure(memlen, itemsize, ndim, shape, strides, offset):
+       """Verify that the parameters represent a valid array within
+          the bounds of the allocated memory:
+              char *mem: start of the physical memory block
+              memlen: length of the physical memory block
+              offset: (char *)buf - mem
+       """
+       if offset % itemsize:
+           return False
+       if offset < 0 or offset+itemsize > memlen:
+           return False
+       if any(v % itemsize for v in strides):
+           return False
+
+       if ndim <= 0:
+           return ndim == 0 and not shape and not strides
+       if 0 in shape:
+           return True
+
+       imin = sum(strides[j]*(shape[j]-1) for j in range(ndim)
+                  if strides[j] <= 0)
+       imax = sum(strides[j]*(shape[j]-1) for j in range(ndim)
+                  if strides[j] > 0)
+
+       return 0 <= offset+imin and offset+imax+itemsize <= memlen
+
+
+PIL-style: shape, strides and suboffsets
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+In addition to the regular items, PIL-style arrays can contain pointers
+that must be followed in order to get to the next element in a dimension.
+For example, the regular three-dimensional C-array ``char v[2][2][3]`` can
+also be viewed as an array of 2 pointers to 2 two-dimensional arrays:
+``char (*v[2])[2][3]``. In suboffsets representation, those two pointers
+can be embedded at the start of :c:member:`~Py_buffer.buf`, pointing
+to two ``char x[2][3]`` arrays that can be located anywhere in memory.
+
+
+Here is a function that returns a pointer to the element in an N-D array
+pointed to by an N-dimensional index when there are both non-NULL strides
+and suboffsets::
+
+   void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,
+                          Py_ssize_t *suboffsets, Py_ssize_t *indices) {
+       char *pointer = (char*)buf;
+       int i;
+       for (i = 0; i < ndim; i++) {
+           pointer += strides[i] * indices[i];
+           if (suboffsets[i] >=0 ) {
+               pointer = *((char**)pointer) + suboffsets[i];
+           }
+       }
+       return (void*)pointer;
+   }
+
+
+Buffer-related functions
+========================
+
+.. c:function:: int PyObject_CheckBuffer(PyObject *obj)
+
+   Return ``1`` if *obj* supports the buffer interface otherwise ``0``.  When ``1`` is
+   returned, it doesn't guarantee that :c:func:`PyObject_GetBuffer` will
+   succeed.  This function always succeeds.
+
+
+.. c:function:: int PyObject_GetBuffer(PyObject *exporter, Py_buffer *view, int flags)
+
+   Send a request to *exporter* to fill in *view* as specified by  *flags*.
+   If the exporter cannot provide a buffer of the exact type, it MUST raise
+   :c:data:`PyExc_BufferError`, set :c:member:`view->obj` to *NULL* and
+   return ``-1``.
+
+   On success, fill in *view*, set :c:member:`view->obj` to a new reference
+   to *exporter* and return 0. In the case of chained buffer providers
+   that redirect requests to a single object, :c:member:`view->obj` MAY
+   refer to this object instead of *exporter* (See :ref:`Buffer Object Structures <buffer-structs>`).
+
+   Successful calls to :c:func:`PyObject_GetBuffer` must be paired with calls
+   to :c:func:`PyBuffer_Release`, similar to :c:func:`malloc` and :c:func:`free`.
+   Thus, after the consumer is done with the buffer, :c:func:`PyBuffer_Release`
+   must be called exactly once.
+
+
+.. c:function:: void PyBuffer_Release(Py_buffer *view)
+
+   Release the buffer *view* and decrement the reference count for
+   :c:member:`view->obj`. This function MUST be called when the buffer
+   is no longer being used, otherwise reference leaks may occur.
+
+   It is an error to call this function on a buffer that was not obtained via
+   :c:func:`PyObject_GetBuffer`.
+
+
+.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
+
+   Return the implied :c:data:`~Py_buffer.itemsize` from :c:data:`~Py_buffer.format`.
+   This function is not yet implemented.
+
+
+.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char order)
+
+   Return ``1`` if the memory defined by the *view* is C-style (*order* is
+   ``'C'``) or Fortran-style (*order* is ``'F'``) :term:`contiguous` or either one
+   (*order* is ``'A'``).  Return ``0`` otherwise.  This function always succeeds.
+
+
+.. c:function:: int PyBuffer_ToContiguous(void *buf, Py_buffer *src, Py_ssize_t len, char order)
+
+   Copy *len* bytes from *src* to its contiguous representation in *buf*.
+   *order* can be ``'C'`` or ``'F'`` (for C-style or Fortran-style ordering).
+   ``0`` is returned on success, ``-1`` on error.
+
+   This function fails if *len* != *src->len*.
+
+
+.. c:function:: void PyBuffer_FillContiguousStrides(int ndims, Py_ssize_t *shape, Py_ssize_t *strides, int itemsize, char order)
+
+   Fill the *strides* array with byte-strides of a :term:`contiguous` (C-style if
+   *order* is ``'C'`` or Fortran-style if *order* is ``'F'``) array of the
+   given shape with the given number of bytes per element.
+
+
+.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *exporter, void *buf, Py_ssize_t len, int readonly, int flags)
+
+   Handle buffer requests for an exporter that wants to expose *buf* of size *len*
+   with writability set according to *readonly*. *buf* is interpreted as a sequence
+   of unsigned bytes.
+
+   The *flags* argument indicates the request type. This function always fills in
+   *view* as specified by flags, unless *buf* has been designated as read-only
+   and :c:macro:`PyBUF_WRITABLE` is set in *flags*.
+
+   On success, set :c:member:`view->obj` to a new reference to *exporter* and
+   return 0. Otherwise, raise :c:data:`PyExc_BufferError`, set
+   :c:member:`view->obj` to *NULL* and return ``-1``;
+
+   If this function is used as part of a :ref:`getbufferproc <buffer-structs>`,
+   *exporter* MUST be set to the exporting object and *flags* must be passed
+   unmodified. Otherwise, *exporter* MUST be NULL.

third_party/python/Doc/c-api/bytearray.rst

@@ -0,0 +1,87 @@
+.. highlightlang:: c
+
+.. _bytearrayobjects:
+
+Byte Array Objects
+------------------
+
+.. index:: object: bytearray
+
+
+.. c:type:: PyByteArrayObject
+
+   This subtype of :c:type:`PyObject` represents a Python bytearray object.
+
+
+.. c:var:: PyTypeObject PyByteArray_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python bytearray type;
+   it is the same object as :class:`bytearray` in the Python layer.
+
+
+Type check macros
+^^^^^^^^^^^^^^^^^
+
+.. c:function:: int PyByteArray_Check(PyObject *o)
+
+   Return true if the object *o* is a bytearray object or an instance of a
+   subtype of the bytearray type.
+
+
+.. c:function:: int PyByteArray_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a bytearray object, but not an instance of a
+   subtype of the bytearray type.
+
+
+Direct API functions
+^^^^^^^^^^^^^^^^^^^^
+
+.. c:function:: PyObject* PyByteArray_FromObject(PyObject *o)
+
+   Return a new bytearray object from any object, *o*, that implements the
+   :ref:`buffer protocol <bufferobjects>`.
+
+   .. XXX expand about the buffer protocol, at least somewhere
+
+
+.. c:function:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)
+
+   Create a new bytearray object from *string* and its length, *len*.  On
+   failure, *NULL* is returned.
+
+
+.. c:function:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
+
+   Concat bytearrays *a* and *b* and return a new bytearray with the result.
+
+
+.. c:function:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
+
+   Return the size of *bytearray* after checking for a *NULL* pointer.
+
+
+.. c:function:: char* PyByteArray_AsString(PyObject *bytearray)
+
+   Return the contents of *bytearray* as a char array after checking for a
+   *NULL* pointer.  The returned array always has an extra
+   null byte appended.
+
+
+.. c:function:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)
+
+   Resize the internal buffer of *bytearray* to *len*.
+
+Macros
+^^^^^^
+
+These macros trade safety for speed and they don't check pointers.
+
+.. c:function:: char* PyByteArray_AS_STRING(PyObject *bytearray)
+
+   Macro version of :c:func:`PyByteArray_AsString`.
+
+
+.. c:function:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
+
+   Macro version of :c:func:`PyByteArray_Size`.

third_party/python/Doc/c-api/bytes.rst

@@ -0,0 +1,202 @@
+.. highlightlang:: c
+
+.. _bytesobjects:
+
+Bytes Objects
+-------------
+
+These functions raise :exc:`TypeError` when expecting a bytes parameter and are
+called with a non-bytes parameter.
+
+.. index:: object: bytes
+
+
+.. c:type:: PyBytesObject
+
+   This subtype of :c:type:`PyObject` represents a Python bytes object.
+
+
+.. c:var:: PyTypeObject PyBytes_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python bytes type; it
+   is the same object as :class:`bytes` in the Python layer.
+
+
+.. c:function:: int PyBytes_Check(PyObject *o)
+
+   Return true if the object *o* is a bytes object or an instance of a subtype
+   of the bytes type.
+
+
+.. c:function:: int PyBytes_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a bytes object, but not an instance of a
+   subtype of the bytes type.
+
+
+.. c:function:: PyObject* PyBytes_FromString(const char *v)
+
+   Return a new bytes object with a copy of the string *v* as value on success,
+   and *NULL* on failure.  The parameter *v* must not be *NULL*; it will not be
+   checked.
+
+
+.. c:function:: PyObject* PyBytes_FromStringAndSize(const char *v, Py_ssize_t len)
+
+   Return a new bytes object with a copy of the string *v* as value and length
+   *len* on success, and *NULL* on failure.  If *v* is *NULL*, the contents of
+   the bytes object are uninitialized.
+
+
+.. c:function:: PyObject* PyBytes_FromFormat(const char *format, ...)
+
+   Take a C :c:func:`printf`\ -style *format* string and a variable number of
+   arguments, calculate the size of the resulting Python bytes object and return
+   a bytes object with the values formatted into it.  The variable arguments
+   must be C types and must correspond exactly to the format characters in the
+   *format* string.  The following format characters are allowed:
+
+   .. % 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|
+
+   +-------------------+---------------+--------------------------------+
+   | Format Characters | Type          | Comment                        |
+   +===================+===============+================================+
+   | :attr:`%%`        | *n/a*         | The literal % character.       |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%c`        | int           | A single byte,                 |
+   |                   |               | represented as a C int.        |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%d`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%d")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%u`        | unsigned int  | Exactly equivalent to          |
+   |                   |               | ``printf("%u")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%ld`       | long          | Exactly equivalent to          |
+   |                   |               | ``printf("%ld")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%lu`       | unsigned long | Exactly equivalent to          |
+   |                   |               | ``printf("%lu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zd`       | Py_ssize_t    | Exactly equivalent to          |
+   |                   |               | ``printf("%zd")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%zu`       | size_t        | Exactly equivalent to          |
+   |                   |               | ``printf("%zu")``.             |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%i`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%i")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%x`        | int           | Exactly equivalent to          |
+   |                   |               | ``printf("%x")``.              |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%s`        | char\*        | A null-terminated C character  |
+   |                   |               | array.                         |
+   +-------------------+---------------+--------------------------------+
+   | :attr:`%p`        | void\*        | The hex representation of a C  |
+   |                   |               | pointer. Mostly equivalent to  |
+   |                   |               | ``printf("%p")`` except that   |
+   |                   |               | it is guaranteed to start with |
+   |                   |               | the literal ``0x`` regardless  |
+   |                   |               | of what the platform's         |
+   |                   |               | ``printf`` yields.             |
+   +-------------------+---------------+--------------------------------+
+
+   An unrecognized format character causes all the rest of the format string to be
+   copied as-is to the result object, and any extra arguments discarded.
+
+
+.. c:function:: PyObject* PyBytes_FromFormatV(const char *format, va_list vargs)
+
+   Identical to :c:func:`PyBytes_FromFormat` except that it takes exactly two
+   arguments.
+
+
+.. c:function:: PyObject* PyBytes_FromObject(PyObject *o)
+
+   Return the bytes representation of object *o* that implements the buffer
+   protocol.
+
+
+.. c:function:: Py_ssize_t PyBytes_Size(PyObject *o)
+
+   Return the length of the bytes in bytes object *o*.
+
+
+.. c:function:: Py_ssize_t PyBytes_GET_SIZE(PyObject *o)
+
+   Macro form of :c:func:`PyBytes_Size` but without error checking.
+
+
+.. c:function:: char* PyBytes_AsString(PyObject *o)
+
+   Return a pointer to the contents of *o*.  The pointer
+   refers to the internal buffer of *o*, which consists of ``len(o) + 1``
+   bytes.  The last byte in the buffer is always null, regardless of
+   whether there are any other null bytes.  The data must not be
+   modified in any way, unless the object was just created using
+   ``PyBytes_FromStringAndSize(NULL, size)``. It must not be deallocated.  If
+   *o* is not a bytes object at all, :c:func:`PyBytes_AsString` returns *NULL*
+   and raises :exc:`TypeError`.
+
+
+.. c:function:: char* PyBytes_AS_STRING(PyObject *string)
+
+   Macro form of :c:func:`PyBytes_AsString` but without error checking.
+
+
+.. c:function:: int PyBytes_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length)
+
+   Return the null-terminated contents of the object *obj*
+   through the output variables *buffer* and *length*.
+
+   If *length* is *NULL*, the bytes object
+   may not contain embedded null bytes;
+   if it does, the function returns ``-1`` and a :exc:`ValueError` is raised.
+
+   The buffer refers to an internal buffer of *obj*, which includes an
+   additional null byte at the end (not counted in *length*).  The data
+   must not be modified in any way, unless the object was just created using
+   ``PyBytes_FromStringAndSize(NULL, size)``.  It must not be deallocated.  If
+   *obj* is not a bytes object at all, :c:func:`PyBytes_AsStringAndSize`
+   returns ``-1`` and raises :exc:`TypeError`.
+
+   .. versionchanged:: 3.5
+      Previously, :exc:`TypeError` was raised when embedded null bytes were
+      encountered in the bytes object.
+
+
+.. c:function:: void PyBytes_Concat(PyObject **bytes, PyObject *newpart)
+
+   Create a new bytes object in *\*bytes* containing the contents of *newpart*
+   appended to *bytes*; the caller will own the new reference.  The reference to
+   the old value of *bytes* will be stolen.  If the new object cannot be
+   created, the old reference to *bytes* will still be discarded and the value
+   of *\*bytes* will be set to *NULL*; the appropriate exception will be set.
+
+
+.. c:function:: void PyBytes_ConcatAndDel(PyObject **bytes, PyObject *newpart)
+
+   Create a new bytes object in *\*bytes* containing the contents of *newpart*
+   appended to *bytes*.  This version decrements the reference count of
+   *newpart*.
+
+
+.. c:function:: int _PyBytes_Resize(PyObject **bytes, Py_ssize_t newsize)
+
+   A way to resize a bytes object even though it is "immutable". Only use this
+   to build up a brand new bytes object; don't use this if the bytes may already
+   be known in other parts of the code.  It is an error to call this function if
+   the refcount on the input bytes object is not one. Pass the address of an
+   existing bytes object as an lvalue (it may be written into), and the new size
+   desired.  On success, *\*bytes* holds the resized bytes object and ``0`` is
+   returned; the address in *\*bytes* may differ from its input value.  If the
+   reallocation fails, the original bytes object at *\*bytes* is deallocated,
+   *\*bytes* is set to *NULL*, :exc:`MemoryError` is set, and ``-1`` is
+   returned.

third_party/python/Doc/c-api/capsule.rst

@@ -0,0 +1,157 @@
+.. highlightlang:: c
+
+.. _capsules:
+
+Capsules
+--------
+
+.. index:: object: Capsule
+
+Refer to :ref:`using-capsules` for more information on using these objects.
+
+.. versionadded:: 3.1
+
+
+.. c:type:: PyCapsule
+
+   This subtype of :c:type:`PyObject` represents an opaque value, useful for C
+   extension modules who need to pass an opaque value (as a :c:type:`void\*`
+   pointer) through Python code to other C code.  It is often used to make a C
+   function pointer defined in one module available to other modules, so the
+   regular import mechanism can be used to access C APIs defined in dynamically
+   loaded modules.
+
+
+.. c:type:: PyCapsule_Destructor
+
+   The type of a destructor callback for a capsule.  Defined as::
+
+      typedef void (*PyCapsule_Destructor)(PyObject *);
+
+   See :c:func:`PyCapsule_New` for the semantics of PyCapsule_Destructor
+   callbacks.
+
+
+.. c:function:: int PyCapsule_CheckExact(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyCapsule`.
+
+
+.. c:function:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
+
+   Create a :c:type:`PyCapsule` encapsulating the *pointer*.  The *pointer*
+   argument may not be *NULL*.
+
+   On failure, set an exception and return *NULL*.
+
+   The *name* string may either be *NULL* or a pointer to a valid C string.  If
+   non-*NULL*, this string must outlive the capsule.  (Though it is permitted to
+   free it inside the *destructor*.)
+
+   If the *destructor* argument is not *NULL*, it will be called with the
+   capsule as its argument when it is destroyed.
+
+   If this capsule will be stored as an attribute of a module, the *name* should
+   be specified as ``modulename.attributename``.  This will enable other modules
+   to import the capsule using :c:func:`PyCapsule_Import`.
+
+
+.. c:function:: void* PyCapsule_GetPointer(PyObject *capsule, const char *name)
+
+   Retrieve the *pointer* stored in the capsule.  On failure, set an exception
+   and return *NULL*.
+
+   The *name* parameter must compare exactly to the name stored in the capsule.
+   If the name stored in the capsule is *NULL*, the *name* passed in must also
+   be *NULL*.  Python uses the C function :c:func:`strcmp` to compare capsule
+   names.
+
+
+.. c:function:: PyCapsule_Destructor PyCapsule_GetDestructor(PyObject *capsule)
+
+   Return the current destructor stored in the capsule.  On failure, set an
+   exception and return *NULL*.
+
+   It is legal for a capsule to have a *NULL* destructor.  This makes a *NULL*
+   return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
+   :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: void* PyCapsule_GetContext(PyObject *capsule)
+
+   Return the current context stored in the capsule.  On failure, set an
+   exception and return *NULL*.
+
+   It is legal for a capsule to have a *NULL* context.  This makes a *NULL*
+   return code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
+   :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: const char* PyCapsule_GetName(PyObject *capsule)
+
+   Return the current name stored in the capsule.  On failure, set an exception
+   and return *NULL*.
+
+   It is legal for a capsule to have a *NULL* name.  This makes a *NULL* return
+   code somewhat ambiguous; use :c:func:`PyCapsule_IsValid` or
+   :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: void* PyCapsule_Import(const char *name, int no_block)
+
+   Import a pointer to a C object from a capsule attribute in a module.  The
+   *name* parameter should specify the full name to the attribute, as in
+   ``module.attribute``.  The *name* stored in the capsule must match this
+   string exactly.  If *no_block* is true, import the module without blocking
+   (using :c:func:`PyImport_ImportModuleNoBlock`).  If *no_block* is false,
+   import the module conventionally (using :c:func:`PyImport_ImportModule`).
+
+   Return the capsule's internal *pointer* on success.  On failure, set an
+   exception and return *NULL*.
+
+
+.. c:function:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
+
+   Determines whether or not *capsule* is a valid capsule.  A valid capsule is
+   non-*NULL*, passes :c:func:`PyCapsule_CheckExact`, has a non-*NULL* pointer
+   stored in it, and its internal name matches the *name* parameter.  (See
+   :c:func:`PyCapsule_GetPointer` for information on how capsule names are
+   compared.)
+
+   In other words, if :c:func:`PyCapsule_IsValid` returns a true value, calls to
+   any of the accessors (any function starting with :c:func:`PyCapsule_Get`) are
+   guaranteed to succeed.
+
+   Return a nonzero value if the object is valid and matches the name passed in.
+   Return ``0`` otherwise.  This function will not fail.
+
+
+.. c:function:: int PyCapsule_SetContext(PyObject *capsule, void *context)
+
+   Set the context pointer inside *capsule* to *context*.
+
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
+
+
+.. c:function:: int PyCapsule_SetDestructor(PyObject *capsule, PyCapsule_Destructor destructor)
+
+   Set the destructor inside *capsule* to *destructor*.
+
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
+
+
+.. c:function:: int PyCapsule_SetName(PyObject *capsule, const char *name)
+
+   Set the name inside *capsule* to *name*.  If non-*NULL*, the name must
+   outlive the capsule.  If the previous *name* stored in the capsule was not
+   *NULL*, no attempt is made to free it.
+
+   Return ``0`` on success.  Return nonzero and set an exception on failure.
+
+
+.. c:function:: int PyCapsule_SetPointer(PyObject *capsule, void *pointer)
+
+   Set the void pointer inside *capsule* to *pointer*.  The pointer may not be
+   *NULL*.
+
+   Return ``0`` on success.  Return nonzero and set an exception on failure.

third_party/python/Doc/c-api/cell.rst

@@ -0,0 +1,62 @@
+.. highlightlang:: c
+
+.. _cell-objects:
+
+Cell Objects
+------------
+
+"Cell" objects are used to implement variables referenced by multiple scopes.
+For each such variable, a cell object is created to store the value; the local
+variables of each stack frame that references the value contains a reference to
+the cells from outer scopes which also use that variable.  When the value is
+accessed, the value contained in the cell is used instead of the cell object
+itself.  This de-referencing of the cell object requires support from the
+generated byte-code; these are not automatically de-referenced when accessed.
+Cell objects are not likely to be useful elsewhere.
+
+
+.. c:type:: PyCellObject
+
+   The C structure used for cell objects.
+
+
+.. c:var:: PyTypeObject PyCell_Type
+
+   The type object corresponding to cell objects.
+
+
+.. c:function:: int PyCell_Check(ob)
+
+   Return true if *ob* is a cell object; *ob* must not be *NULL*.
+
+
+.. c:function:: PyObject* PyCell_New(PyObject *ob)
+
+   Create and return a new cell object containing the value *ob*. The parameter may
+   be *NULL*.
+
+
+.. c:function:: PyObject* PyCell_Get(PyObject *cell)
+
+   Return the contents of the cell *cell*.
+
+
+.. c:function:: PyObject* PyCell_GET(PyObject *cell)
+
+   Return the contents of the cell *cell*, but without checking that *cell* is
+   non-*NULL* and a cell object.
+
+
+.. c:function:: int PyCell_Set(PyObject *cell, PyObject *value)
+
+   Set the contents of the cell object *cell* to *value*.  This releases the
+   reference to any current content of the cell. *value* may be *NULL*.  *cell*
+   must be non-*NULL*; if it is not a cell object, ``-1`` will be returned.  On
+   success, ``0`` will be returned.
+
+
+.. c:function:: void PyCell_SET(PyObject *cell, PyObject *value)
+
+   Sets the value of the cell object *cell* to *value*.  No reference counts are
+   adjusted, and no checks are made for safety; *cell* must be non-*NULL* and must
+   be a cell object.

third_party/python/Doc/c-api/code.rst

@@ -0,0 +1,48 @@
+.. highlightlang:: c
+
+.. _codeobjects:
+
+.. index:: object; code, code object
+
+Code Objects
+------------
+
+.. sectionauthor:: Jeffrey Yasskin <jyasskin@gmail.com>
+
+Code objects are a low-level detail of the CPython implementation.
+Each one represents a chunk of executable code that hasn't yet been
+bound into a function.
+
+.. c:type:: PyCodeObject
+
+   The C structure of the objects used to describe code objects.  The
+   fields of this type are subject to change at any time.
+
+
+.. c:var:: PyTypeObject PyCode_Type
+
+   This is an instance of :c:type:`PyTypeObject` representing the Python
+   :class:`code` type.
+
+
+.. c:function:: int PyCode_Check(PyObject *co)
+
+   Return true if *co* is a :class:`code` object.
+
+.. c:function:: int PyCode_GetNumFree(PyCodeObject *co)
+
+   Return the number of free variables in *co*.
+
+.. 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 *lnotab)
+
+   Return a new code object.  If you need a dummy code object to
+   create a frame, use :c:func:`PyCode_NewEmpty` instead.  Calling
+   :c:func:`PyCode_New` directly can bind you to a precise Python
+   version since the definition of the bytecode changes often.
+
+
+.. c:function:: PyCodeObject* PyCode_NewEmpty(const char *filename, const char *funcname, int firstlineno)
+
+   Return a new empty code object with the specified filename,
+   function name, and first line number.  It is illegal to
+   :func:`exec` or :func:`eval` the resulting code object.

third_party/python/Doc/c-api/codec.rst

@@ -0,0 +1,123 @@
+.. _codec-registry:
+
+Codec registry and support functions
+====================================
+
+.. c:function:: int PyCodec_Register(PyObject *search_function)
+
+   Register a new codec search function.
+
+   As side effect, this tries to load the :mod:`encodings` package, if not yet
+   done, to make sure that it is always first in the list of search functions.
+
+.. c:function:: int PyCodec_KnownEncoding(const char *encoding)
+
+   Return ``1`` or ``0`` depending on whether there is a registered codec for
+   the given *encoding*.  This function always succeeds.
+
+.. c:function:: PyObject* PyCodec_Encode(PyObject *object, const char *encoding, const char *errors)
+
+   Generic codec based encoding API.
+
+   *object* is passed through the encoder function found for the given
+   *encoding* using the error handling method defined by *errors*.  *errors* may
+   be *NULL* to use the default method defined for the codec.  Raises a
+   :exc:`LookupError` if no encoder can be found.
+
+.. c:function:: PyObject* PyCodec_Decode(PyObject *object, const char *encoding, const char *errors)
+
+   Generic codec based decoding API.
+
+   *object* is passed through the decoder function found for the given
+   *encoding* using the error handling method defined by *errors*.  *errors* may
+   be *NULL* to use the default method defined for the codec.  Raises a
+   :exc:`LookupError` if no encoder can be found.
+
+
+Codec lookup API
+----------------
+
+In the following functions, the *encoding* string is looked up converted to all
+lower-case characters, which makes encodings looked up through this mechanism
+effectively case-insensitive.  If no codec is found, a :exc:`KeyError` is set
+and *NULL* returned.
+
+.. c:function:: PyObject* PyCodec_Encoder(const char *encoding)
+
+   Get an encoder function for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_Decoder(const char *encoding)
+
+   Get a decoder function for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
+
+   Get an :class:`~codecs.IncrementalEncoder` object for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
+
+   Get an :class:`~codecs.IncrementalDecoder` object for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
+
+   Get a :class:`~codecs.StreamReader` factory function for the given *encoding*.
+
+.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors)
+
+   Get a :class:`~codecs.StreamWriter` factory function for the given *encoding*.
+
+
+Registry API for Unicode encoding error handlers
+------------------------------------------------
+
+.. c:function:: int PyCodec_RegisterError(const char *name, PyObject *error)
+
+   Register the error handling callback function *error* under the given *name*.
+   This callback function will be called by a codec when it encounters
+   unencodable characters/undecodable bytes and *name* is specified as the error
+   parameter in the call to the encode/decode function.
+
+   The callback gets a single argument, an instance of
+   :exc:`UnicodeEncodeError`, :exc:`UnicodeDecodeError` or
+   :exc:`UnicodeTranslateError` that holds information about the problematic
+   sequence of characters or bytes and their offset in the original string (see
+   :ref:`unicodeexceptions` for functions to extract this information).  The
+   callback must either raise the given exception, or return a two-item tuple
+   containing the replacement for the problematic sequence, and an integer
+   giving the offset in the original string at which encoding/decoding should be
+   resumed.
+
+   Return ``0`` on success, ``-1`` on error.
+
+.. c:function:: PyObject* PyCodec_LookupError(const char *name)
+
+   Lookup the error handling callback function registered under *name*.  As a
+   special case *NULL* can be passed, in which case the error handling callback
+   for "strict" will be returned.
+
+.. c:function:: PyObject* PyCodec_StrictErrors(PyObject *exc)
+
+   Raise *exc* as an exception.
+
+.. c:function:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)
+
+   Ignore the unicode error, skipping the faulty input.
+
+.. c:function:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)
+
+   Replace the unicode encode error with ``?`` or ``U+FFFD``.
+
+.. c:function:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
+
+   Replace the unicode encode error with XML character references.
+
+.. c:function:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)
+
+   Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and
+   ``\U``).
+
+.. c:function:: PyObject* PyCodec_NameReplaceErrors(PyObject *exc)
+
+   Replace the unicode encode error with ``\N{...}`` escapes.
+
+   .. versionadded:: 3.5

third_party/python/Doc/c-api/complex.rst

@@ -0,0 +1,132 @@
+.. highlightlang:: c
+
+.. _complexobjects:
+
+Complex Number Objects
+----------------------
+
+.. index:: object: complex number
+
+Python's complex number objects are implemented as two distinct types when
+viewed from the C API:  one is the Python object exposed to Python programs, and
+the other is a C structure which represents the actual complex number value.
+The API provides functions for working with both.
+
+
+Complex Numbers as C Structures
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Note that the functions which accept these structures as parameters and return
+them as results do so *by value* rather than dereferencing them through
+pointers.  This is consistent throughout the API.
+
+
+.. c:type:: Py_complex
+
+   The C structure which corresponds to the value portion of a Python complex
+   number object.  Most of the functions for dealing with complex number objects
+   use structures of this type as input or output values, as appropriate.  It is
+   defined as::
+
+      typedef struct {
+         double real;
+         double imag;
+      } Py_complex;
+
+
+.. c:function:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
+
+   Return the sum of two complex numbers, using the C :c:type:`Py_complex`
+   representation.
+
+
+.. c:function:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
+
+   Return the difference between two complex numbers, using the C
+   :c:type:`Py_complex` representation.
+
+
+.. c:function:: Py_complex _Py_c_neg(Py_complex complex)
+
+   Return the negation of the complex number *complex*, using the C
+   :c:type:`Py_complex` representation.
+
+
+.. c:function:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
+
+   Return the product of two complex numbers, using the C :c:type:`Py_complex`
+   representation.
+
+
+.. c:function:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
+
+   Return the quotient of two complex numbers, using the C :c:type:`Py_complex`
+   representation.
+
+   If *divisor* is null, this method returns zero and sets
+   :c:data:`errno` to :c:data:`EDOM`.
+
+
+.. c:function:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
+
+   Return the exponentiation of *num* by *exp*, using the C :c:type:`Py_complex`
+   representation.
+
+   If *num* is null and *exp* is not a positive real number,
+   this method returns zero and sets :c:data:`errno` to :c:data:`EDOM`.
+
+
+Complex Numbers as Python Objects
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+
+.. c:type:: PyComplexObject
+
+   This subtype of :c:type:`PyObject` represents a Python complex number object.
+
+
+.. c:var:: PyTypeObject PyComplex_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python complex number
+   type. It is the same object as :class:`complex` in the Python layer.
+
+
+.. c:function:: int PyComplex_Check(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyComplexObject` or a subtype of
+   :c:type:`PyComplexObject`.
+
+
+.. c:function:: int PyComplex_CheckExact(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyComplexObject`, but not a subtype of
+   :c:type:`PyComplexObject`.
+
+
+.. c:function:: PyObject* PyComplex_FromCComplex(Py_complex v)
+
+   Create a new Python complex number object from a C :c:type:`Py_complex` value.
+
+
+.. c:function:: PyObject* PyComplex_FromDoubles(double real, double imag)
+
+   Return a new :c:type:`PyComplexObject` object from *real* and *imag*.
+
+
+.. c:function:: double PyComplex_RealAsDouble(PyObject *op)
+
+   Return the real part of *op* as a C :c:type:`double`.
+
+
+.. c:function:: double PyComplex_ImagAsDouble(PyObject *op)
+
+   Return the imaginary part of *op* as a C :c:type:`double`.
+
+
+.. c:function:: Py_complex PyComplex_AsCComplex(PyObject *op)
+
+   Return the :c:type:`Py_complex` value of the complex number *op*.
+
+   If *op* is not a Python complex number object but has a :meth:`__complex__`
+   method, this method will first be called to convert *op* to a Python complex
+   number object. Upon failure, this method returns ``-1.0`` as a real value.

third_party/python/Doc/c-api/concrete.rst

@@ -0,0 +1,117 @@
+.. highlightlang:: c
+
+
+.. _concrete:
+
+**********************
+Concrete Objects Layer
+**********************
+
+The functions in this chapter are specific to certain Python object types.
+Passing them an object of the wrong type is not a good idea; if you receive an
+object from a Python program and you are not sure that it has the right type,
+you must perform a type check first; for example, to check that an object is a
+dictionary, use :c:func:`PyDict_Check`.  The chapter is structured like the
+"family tree" of Python object types.
+
+.. warning::
+
+   While the functions described in this chapter carefully check the type of the
+   objects which are passed in, many of them do not check for *NULL* being passed
+   instead of a valid object.  Allowing *NULL* to be passed in can cause memory
+   access violations and immediate termination of the interpreter.
+
+
+.. _fundamental:
+
+Fundamental Objects
+===================
+
+This section describes Python type objects and the singleton object ``None``.
+
+.. toctree::
+
+   type.rst
+   none.rst
+
+
+.. _numericobjects:
+
+Numeric Objects
+===============
+
+.. index:: object: numeric
+
+.. toctree::
+
+   long.rst
+   bool.rst
+   float.rst
+   complex.rst
+
+
+.. _sequenceobjects:
+
+Sequence Objects
+================
+
+.. index:: object: sequence
+
+Generic operations on sequence objects were discussed in the previous chapter;
+this section deals with the specific kinds of sequence objects that are
+intrinsic to the Python language.
+
+.. XXX sort out unicode, str, bytes and bytearray
+
+.. toctree::
+
+   bytes.rst
+   bytearray.rst
+   unicode.rst
+   tuple.rst
+   list.rst
+
+
+.. _mapobjects:
+
+Container Objects
+=================
+
+.. index:: object: mapping
+
+.. toctree::
+
+   dict.rst
+   set.rst
+
+
+.. _otherobjects:
+
+Function Objects
+================
+
+.. toctree::
+
+   function.rst
+   method.rst
+   cell.rst
+   code.rst
+
+
+Other Objects
+=============
+
+.. toctree::
+
+   file.rst
+   module.rst
+   iterator.rst
+   descriptor.rst
+   slice.rst
+   memoryview.rst
+   weakref.rst
+   capsule.rst
+   gen.rst
+   coro.rst
+   datetime.rst
+

third_party/python/Doc/c-api/conversion.rst

@@ -0,0 +1,131 @@
+.. highlightlang:: c
+
+.. _string-conversion:
+
+String conversion and formatting
+================================
+
+Functions for number conversion and formatted string output.
+
+
+.. c:function:: int PyOS_snprintf(char *str, size_t size,  const char *format, ...)
+
+   Output not more than *size* bytes to *str* according to the format string
+   *format* and the extra arguments. See the Unix man page :manpage:`snprintf(2)`.
+
+
+.. c:function:: int PyOS_vsnprintf(char *str, size_t size, const char *format, va_list va)
+
+   Output not more than *size* bytes to *str* according to the format string
+   *format* and the variable argument list *va*. Unix man page
+   :manpage:`vsnprintf(2)`.
+
+:c:func:`PyOS_snprintf` and :c:func:`PyOS_vsnprintf` wrap the Standard C library
+functions :c:func:`snprintf` and :c:func:`vsnprintf`. Their purpose is to
+guarantee consistent behavior in corner cases, which the Standard C functions do
+not.
+
+The wrappers ensure that *str*[*size*-1] is always ``'\0'`` upon return. They
+never write more than *size* bytes (including the trailing ``'\0'``) into str.
+Both functions require that ``str != NULL``, ``size > 0`` and ``format !=
+NULL``.
+
+If the platform doesn't have :c:func:`vsnprintf` and the buffer size needed to
+avoid truncation exceeds *size* by more than 512 bytes, Python aborts with a
+*Py_FatalError*.
+
+The return value (*rv*) for these functions should be interpreted as follows:
+
+* When ``0 <= rv < size``, the output conversion was successful and *rv*
+  characters were written to *str* (excluding the trailing ``'\0'`` byte at
+  *str*[*rv*]).
+
+* When ``rv >= size``, the output conversion was truncated and a buffer with
+  ``rv + 1`` bytes would have been needed to succeed. *str*[*size*-1] is ``'\0'``
+  in this case.
+
+* When ``rv < 0``, "something bad happened." *str*[*size*-1] is ``'\0'`` in
+  this case too, but the rest of *str* is undefined. The exact cause of the error
+  depends on the underlying platform.
+
+The following functions provide locale-independent string to number conversions.
+
+
+.. c:function:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
+
+   Convert a string ``s`` to a :c:type:`double`, raising a Python
+   exception on failure.  The set of accepted strings corresponds to
+   the set of strings accepted by Python's :func:`float` constructor,
+   except that ``s`` must not have leading or trailing whitespace.
+   The conversion is independent of the current locale.
+
+   If ``endptr`` is ``NULL``, convert the whole string.  Raise
+   ValueError and return ``-1.0`` if the string is not a valid
+   representation of a floating-point number.
+
+   If endptr is not ``NULL``, convert as much of the string as
+   possible and set ``*endptr`` to point to the first unconverted
+   character.  If no initial segment of the string is the valid
+   representation of a floating-point number, set ``*endptr`` to point
+   to the beginning of the string, raise ValueError, and return
+   ``-1.0``.
+
+   If ``s`` represents a value that is too large to store in a float
+   (for example, ``"1e500"`` is such a string on many platforms) then
+   if ``overflow_exception`` is ``NULL`` return ``Py_HUGE_VAL`` (with
+   an appropriate sign) and don't set any exception.  Otherwise,
+   ``overflow_exception`` must point to a Python exception object;
+   raise that exception and return ``-1.0``.  In both cases, set
+   ``*endptr`` to point to the first character after the converted value.
+
+   If any other error occurs during the conversion (for example an
+   out-of-memory error), set the appropriate Python exception and
+   return ``-1.0``.
+
+   .. versionadded:: 3.1
+
+
+.. c:function:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
+
+   Convert a :c:type:`double` *val* to a string using supplied
+   *format_code*, *precision*, and *flags*.
+
+   *format_code* must be one of ``'e'``, ``'E'``, ``'f'``, ``'F'``,
+   ``'g'``, ``'G'`` or ``'r'``.  For ``'r'``, the supplied *precision*
+   must be 0 and is ignored.  The ``'r'`` format code specifies the
+   standard :func:`repr` format.
+
+   *flags* can be zero or more of the values *Py_DTSF_SIGN*,
+   *Py_DTSF_ADD_DOT_0*, or *Py_DTSF_ALT*, or-ed together:
+
+   * *Py_DTSF_SIGN* means to always precede the returned string with a sign
+     character, even if *val* is non-negative.
+
+   * *Py_DTSF_ADD_DOT_0* means to ensure that the returned string will not look
+     like an integer.
+
+   * *Py_DTSF_ALT* means to apply "alternate" formatting rules.  See the
+     documentation for the :c:func:`PyOS_snprintf` ``'#'`` specifier for
+     details.
+
+   If *ptype* is non-NULL, then the value it points to will be set to one of
+   *Py_DTST_FINITE*, *Py_DTST_INFINITE*, or *Py_DTST_NAN*, signifying that
+   *val* is a finite number, an infinite number, or not a number, respectively.
+
+   The return value is a pointer to *buffer* with the converted string or
+   *NULL* if the conversion failed. The caller is responsible for freeing the
+   returned string by calling :c:func:`PyMem_Free`.
+
+   .. versionadded:: 3.1
+
+
+.. c:function:: int PyOS_stricmp(const char *s1, const char *s2)
+
+   Case insensitive comparison of strings. The function works almost
+   identically to :c:func:`strcmp` except that it ignores the case.
+
+
+.. c:function:: int PyOS_strnicmp(const char *s1, const char *s2, Py_ssize_t  size)
+
+   Case insensitive comparison of strings. The function works almost
+   identically to :c:func:`strncmp` except that it ignores the case.

third_party/python/Doc/c-api/coro.rst

@@ -0,0 +1,34 @@
+.. highlightlang:: c
+
+.. _coro-objects:
+
+Coroutine Objects
+-----------------
+
+.. versionadded:: 3.5
+
+Coroutine objects are what functions declared with an ``async`` keyword
+return.
+
+
+.. c:type:: PyCoroObject
+
+   The C structure used for coroutine objects.
+
+
+.. c:var:: PyTypeObject PyCoro_Type
+
+   The type object corresponding to coroutine objects.
+
+
+.. c:function:: int PyCoro_CheckExact(PyObject *ob)
+
+   Return true if *ob*'s type is *PyCoro_Type*; *ob* must not be *NULL*.
+
+
+.. c:function:: PyObject* PyCoro_New(PyFrameObject *frame, PyObject *name, PyObject *qualname)
+
+   Create and return a new coroutine object based on the *frame* object,
+   with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
+   A reference to *frame* is stolen by this function.  The *frame* argument
+   must not be *NULL*.

third_party/python/Doc/c-api/datetime.rst

@@ -0,0 +1,209 @@
+.. highlightlang:: c
+
+.. _datetimeobjects:
+
+DateTime Objects
+----------------
+
+Various date and time objects are supplied by the :mod:`datetime` module.
+Before using any of these functions, the header file :file:`datetime.h` must be
+included in your source (note that this is not included by :file:`Python.h`),
+and the macro :c:macro:`PyDateTime_IMPORT` must be invoked, usually as part of
+the module initialisation function.  The macro puts a pointer to a C structure
+into a static variable, :c:data:`PyDateTimeAPI`, that is used by the following
+macros.
+
+Type-check macros:
+
+.. c:function:: int PyDate_Check(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_DateType` or a subtype of
+   :c:data:`PyDateTime_DateType`.  *ob* must not be *NULL*.
+
+
+.. c:function:: int PyDate_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be
+   *NULL*.
+
+
+.. c:function:: int PyDateTime_Check(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType` or a subtype of
+   :c:data:`PyDateTime_DateTimeType`.  *ob* must not be *NULL*.
+
+
+.. c:function:: int PyDateTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not
+   be *NULL*.
+
+
+.. c:function:: int PyTime_Check(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_TimeType` or a subtype of
+   :c:data:`PyDateTime_TimeType`.  *ob* must not be *NULL*.
+
+
+.. c:function:: int PyTime_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be
+   *NULL*.
+
+
+.. c:function:: int PyDelta_Check(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_DeltaType` or a subtype of
+   :c:data:`PyDateTime_DeltaType`.  *ob* must not be *NULL*.
+
+
+.. c:function:: int PyDelta_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be
+   *NULL*.
+
+
+.. c:function:: int PyTZInfo_Check(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType` or a subtype of
+   :c:data:`PyDateTime_TZInfoType`.  *ob* must not be *NULL*.
+
+
+.. c:function:: int PyTZInfo_CheckExact(PyObject *ob)
+
+   Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be
+   *NULL*.
+
+
+Macros to create objects:
+
+.. c:function:: PyObject* PyDate_FromDate(int year, int month, int day)
+
+   Return a ``datetime.date`` object with the specified year, month and day.
+
+
+.. c:function:: PyObject* PyDateTime_FromDateAndTime(int year, int month, int day, int hour, int minute, int second, int usecond)
+
+   Return a ``datetime.datetime`` object with the specified year, month, day, hour,
+   minute, second and microsecond.
+
+
+.. c:function:: PyObject* PyTime_FromTime(int hour, int minute, int second, int usecond)
+
+   Return a ``datetime.time`` object with the specified hour, minute, second and
+   microsecond.
+
+
+.. c:function:: PyObject* PyDelta_FromDSU(int days, int seconds, int useconds)
+
+   Return a ``datetime.timedelta`` object representing the given number of days,
+   seconds and microseconds.  Normalization is performed so that the resulting
+   number of microseconds and seconds lie in the ranges documented for
+   ``datetime.timedelta`` objects.
+
+
+Macros to extract fields from date objects.  The argument must be an instance of
+:c:data:`PyDateTime_Date`, including subclasses (such as
+:c:data:`PyDateTime_DateTime`).  The argument must not be *NULL*, and the type is
+not checked:
+
+.. c:function:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
+
+   Return the year, as a positive int.
+
+
+.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
+
+   Return the month, as an int from 1 through 12.
+
+
+.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o)
+
+   Return the day, as an int from 1 through 31.
+
+
+Macros to extract fields from datetime objects.  The argument must be an
+instance of :c:data:`PyDateTime_DateTime`, including subclasses. The argument
+must not be *NULL*, and the type is not checked:
+
+.. c:function:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
+
+   Return the hour, as an int from 0 through 23.
+
+
+.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
+
+   Return the minute, as an int from 0 through 59.
+
+
+.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
+
+   Return the second, as an int from 0 through 59.
+
+
+.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+
+Macros to extract fields from time objects.  The argument must be an instance of
+:c:data:`PyDateTime_Time`, including subclasses. The argument must not be *NULL*,
+and the type is not checked:
+
+.. c:function:: int PyDateTime_TIME_GET_HOUR(PyDateTime_Time *o)
+
+   Return the hour, as an int from 0 through 23.
+
+
+.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o)
+
+   Return the minute, as an int from 0 through 59.
+
+
+.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o)
+
+   Return the second, as an int from 0 through 59.
+
+
+.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o)
+
+   Return the microsecond, as an int from 0 through 999999.
+
+
+Macros to extract fields from time delta objects.  The argument must be an
+instance of :c:data:`PyDateTime_Delta`, including subclasses. The argument must
+not be *NULL*, and the type is not checked:
+
+.. c:function:: int PyDateTime_DELTA_GET_DAYS(PyDateTime_Delta *o)
+
+   Return the number of days, as an int from -999999999 to 999999999.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: int PyDateTime_DELTA_GET_SECONDS(PyDateTime_Delta *o)
+
+   Return the number of seconds, as an int from 0 through 86399.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: int PyDateTime_DELTA_GET_MICROSECONDS(PyDateTime_Delta *o)
+
+   Return the number of microseconds, as an int from 0 through 999999.
+
+   .. versionadded:: 3.3
+
+
+Macros for the convenience of modules implementing the DB API:
+
+.. c:function:: PyObject* PyDateTime_FromTimestamp(PyObject *args)
+
+   Create and return a new ``datetime.datetime`` object given an argument tuple
+   suitable for passing to ``datetime.datetime.fromtimestamp()``.
+
+
+.. c:function:: PyObject* PyDate_FromTimestamp(PyObject *args)
+
+   Create and return a new ``datetime.date`` object given an argument tuple
+   suitable for passing to ``datetime.date.fromtimestamp()``.

third_party/python/Doc/c-api/descriptor.rst

@@ -0,0 +1,40 @@
+.. highlightlang:: c
+
+.. _descriptor-objects:
+
+Descriptor Objects
+------------------
+
+"Descriptors" are objects that describe some attribute of an object. They are
+found in the dictionary of type objects.
+
+.. XXX document these!
+
+.. c:var:: PyTypeObject PyProperty_Type
+
+   The type object for the built-in descriptor types.
+
+
+.. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset)
+
+
+.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth)
+
+
+.. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth)
+
+
+.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped)
+
+
+.. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method)
+
+
+.. c:function:: int PyDescr_IsData(PyObject *descr)
+
+   Return true if the descriptor objects *descr* describes a data attribute, or
+   false if it describes a method.  *descr* must be a descriptor object; there is
+   no error checking.
+
+
+.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *)

third_party/python/Doc/c-api/dict.rst

@@ -0,0 +1,240 @@
+.. highlightlang:: c
+
+.. _dictobjects:
+
+Dictionary Objects
+------------------
+
+.. index:: object: dictionary
+
+
+.. c:type:: PyDictObject
+
+   This subtype of :c:type:`PyObject` represents a Python dictionary object.
+
+
+.. c:var:: PyTypeObject PyDict_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python dictionary
+   type.  This is the same object as :class:`dict` in the Python layer.
+
+
+.. c:function:: int PyDict_Check(PyObject *p)
+
+   Return true if *p* is a dict object or an instance of a subtype of the dict
+   type.
+
+
+.. c:function:: int PyDict_CheckExact(PyObject *p)
+
+   Return true if *p* is a dict object, but not an instance of a subtype of
+   the dict type.
+
+
+.. c:function:: PyObject* PyDict_New()
+
+   Return a new empty dictionary, or *NULL* on failure.
+
+
+.. c:function:: PyObject* PyDictProxy_New(PyObject *mapping)
+
+   Return a :class:`types.MappingProxyType` object for a mapping which
+   enforces read-only behavior.  This is normally used to create a view to
+   prevent modification of the dictionary for non-dynamic class types.
+
+
+.. c:function:: void PyDict_Clear(PyObject *p)
+
+   Empty an existing dictionary of all key-value pairs.
+
+
+.. c:function:: int PyDict_Contains(PyObject *p, PyObject *key)
+
+   Determine if dictionary *p* contains *key*.  If an item in *p* is matches
+   *key*, return ``1``, otherwise return ``0``.  On error, return ``-1``.
+   This is equivalent to the Python expression ``key in p``.
+
+
+.. c:function:: PyObject* PyDict_Copy(PyObject *p)
+
+   Return a new dictionary that contains the same key-value pairs as *p*.
+
+
+.. c:function:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)
+
+   Insert *value* into the dictionary *p* with a key of *key*.  *key* must be
+   :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
+   ``0`` on success or ``-1`` on failure.
+
+
+.. c:function:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)
+
+   .. index:: single: PyUnicode_FromString()
+
+   Insert *value* into the dictionary *p* using *key* as a key. *key* should
+   be a :c:type:`char\*`.  The key object is created using
+   ``PyUnicode_FromString(key)``.  Return ``0`` on success or ``-1`` on
+   failure.
+
+
+.. c:function:: int PyDict_DelItem(PyObject *p, PyObject *key)
+
+   Remove the entry in dictionary *p* with key *key*. *key* must be hashable;
+   if it isn't, :exc:`TypeError` is raised.  Return ``0`` on success or ``-1``
+   on failure.
+
+
+.. c:function:: int PyDict_DelItemString(PyObject *p, const char *key)
+
+   Remove the entry in dictionary *p* which has a key specified by the string
+   *key*.  Return ``0`` on success or ``-1`` on failure.
+
+
+.. c:function:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)
+
+   Return the object from dictionary *p* which has a key *key*.  Return *NULL*
+   if the key *key* is not present, but *without* setting an exception.
+
+   Note that exceptions which occur while calling :meth:`__hash__` and
+   :meth:`__eq__` methods will get suppressed.
+   To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+
+
+.. c:function:: PyObject* PyDict_GetItemWithError(PyObject *p, PyObject *key)
+
+   Variant of :c:func:`PyDict_GetItem` that does not suppress
+   exceptions. Return *NULL* **with** an exception set if an exception
+   occurred.  Return *NULL* **without** an exception set if the key
+   wasn't present.
+
+
+.. c:function:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
+
+   This is the same as :c:func:`PyDict_GetItem`, but *key* is specified as a
+   :c:type:`char\*`, rather than a :c:type:`PyObject\*`.
+
+   Note that exceptions which occur while calling :meth:`__hash__` and
+   :meth:`__eq__` methods and creating a temporary string object
+   will get suppressed.
+   To get error reporting use :c:func:`PyDict_GetItemWithError()` instead.
+
+
+.. 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.
+
+   .. versionadded:: 3.4
+
+.. c:function:: PyObject* PyDict_Items(PyObject *p)
+
+   Return a :c:type:`PyListObject` containing all the items from the dictionary.
+
+
+.. c:function:: PyObject* PyDict_Keys(PyObject *p)
+
+   Return a :c:type:`PyListObject` containing all the keys from the dictionary.
+
+
+.. c:function:: PyObject* PyDict_Values(PyObject *p)
+
+   Return a :c:type:`PyListObject` containing all the values from the dictionary
+   *p*.
+
+
+.. c:function:: Py_ssize_t PyDict_Size(PyObject *p)
+
+   .. index:: builtin: len
+
+   Return the number of items in the dictionary.  This is equivalent to
+   ``len(p)`` on a dictionary.
+
+
+.. c:function:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
+
+   Iterate over all key-value pairs in the dictionary *p*.  The
+   :c:type:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``
+   prior to the first call to this function to start the iteration; the
+   function returns true for each pair in the dictionary, and false once all
+   pairs have been reported.  The parameters *pkey* and *pvalue* should either
+   point to :c:type:`PyObject\*` variables that will be filled in with each key
+   and value, respectively, or may be *NULL*.  Any references returned through
+   them are borrowed.  *ppos* should not be altered during iteration. Its
+   value represents offsets within the internal dictionary structure, and
+   since the structure is sparse, the offsets are not consecutive.
+
+   For example::
+
+      PyObject *key, *value;
+      Py_ssize_t pos = 0;
+
+      while (PyDict_Next(self->dict, &pos, &key, &value)) {
+          /* do something interesting with the values... */
+          ...
+      }
+
+   The dictionary *p* should not be mutated during iteration.  It is safe to
+   modify the values of the keys as you iterate over the dictionary, but only
+   so long as the set of keys does not change.  For example::
+
+      PyObject *key, *value;
+      Py_ssize_t pos = 0;
+
+      while (PyDict_Next(self->dict, &pos, &key, &value)) {
+          long i = PyLong_AsLong(value);
+          if (i == -1 && PyErr_Occurred()) {
+              return -1;
+          }
+          PyObject *o = PyLong_FromLong(i + 1);
+          if (o == NULL)
+              return -1;
+          if (PyDict_SetItem(self->dict, key, o) < 0) {
+              Py_DECREF(o);
+              return -1;
+          }
+          Py_DECREF(o);
+      }
+
+
+.. c:function:: int PyDict_Merge(PyObject *a, PyObject *b, int override)
+
+   Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
+   *b* may be a dictionary, or any object supporting :c:func:`PyMapping_Keys`
+   and :c:func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*
+   will be replaced if a matching key is found in *b*, otherwise pairs will
+   only be added if there is not a matching key in *a*. Return ``0`` on
+   success or ``-1`` if an exception was raised.
+
+
+.. c:function:: int PyDict_Update(PyObject *a, PyObject *b)
+
+   This is the same as ``PyDict_Merge(a, b, 1)`` in C, and is similar to
+   ``a.update(b)`` in Python except that :c:func:`PyDict_Update` doesn't fall
+   back to the iterating over a sequence of key value pairs if the second
+   argument has no "keys" attribute.  Return ``0`` on success or ``-1`` if an
+   exception was raised.
+
+
+.. c:function:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)
+
+   Update or merge into dictionary *a*, from the key-value pairs in *seq2*.
+   *seq2* must be an iterable object producing iterable objects of length 2,
+   viewed as key-value pairs.  In case of duplicate keys, the last wins if
+   *override* is true, else the first wins. Return ``0`` on success or ``-1``
+   if an exception was raised. Equivalent Python (except for the return
+   value)::
+
+      def PyDict_MergeFromSeq2(a, seq2, override):
+          for key, value in seq2:
+              if override or key not in a:
+                  a[key] = value
+
+
+.. c:function:: int PyDict_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+
+   .. versionadded:: 3.3

third_party/python/Doc/c-api/file.rst

@@ -0,0 +1,76 @@
+.. highlightlang:: c
+
+.. _fileobjects:
+
+File Objects
+------------
+
+.. index:: object: file
+
+These APIs are a minimal emulation of the Python 2 C API for built-in file
+objects, which used to rely on the buffered I/O (:c:type:`FILE\*`) support
+from the C standard library.  In Python 3, files and streams use the new
+:mod:`io` module, which defines several layers over the low-level unbuffered
+I/O of the operating system.  The functions described below are
+convenience C wrappers over these new APIs, and meant mostly for internal
+error reporting in the interpreter; third-party code is advised to access
+the :mod:`io` APIs instead.
+
+
+.. c:function:: PyFile_FromFd(int fd, const char *name, const char *mode, int buffering, const char *encoding, const char *errors, const char *newline, int closefd)
+
+   Create a Python file object from the file descriptor of an already
+   opened file *fd*.  The arguments *name*, *encoding*, *errors* and *newline*
+   can be *NULL* to use the defaults; *buffering* can be *-1* to use the
+   default. *name* is ignored and kept for backward compatibility. Return
+   *NULL* on failure. For a more comprehensive description of the arguments,
+   please refer to the :func:`io.open` function documentation.
+
+   .. warning::
+
+     Since Python streams have their own buffering layer, mixing them with
+     OS-level file descriptors can produce various issues (such as unexpected
+     ordering of data).
+
+   .. versionchanged:: 3.2
+      Ignore *name* attribute.
+
+
+.. c:function:: int PyObject_AsFileDescriptor(PyObject *p)
+
+   Return the file descriptor associated with *p* as an :c:type:`int`.  If the
+   object is an integer, its value is returned.  If not, the
+   object's :meth:`~io.IOBase.fileno` method is called if it exists; the
+   method must return an integer, which is returned as the file descriptor
+   value.  Sets an exception and returns ``-1`` on failure.
+
+
+.. c:function:: PyObject* PyFile_GetLine(PyObject *p, int n)
+
+   .. index:: single: EOFError (built-in exception)
+
+   Equivalent to ``p.readline([n])``, this function reads one line from the
+   object *p*.  *p* may be a file object or any object with a
+   :meth:`~io.IOBase.readline`
+   method.  If *n* is ``0``, exactly one line is read, regardless of the length of
+   the line.  If *n* is greater than ``0``, no more than *n* bytes will be read
+   from the file; a partial line can be returned.  In both cases, an empty string
+   is returned if the end of the file is reached immediately.  If *n* is less than
+   ``0``, however, one line is read regardless of length, but :exc:`EOFError` is
+   raised if the end of the file is reached immediately.
+
+
+.. c:function:: int PyFile_WriteObject(PyObject *obj, PyObject *p, int flags)
+
+   .. index:: single: Py_PRINT_RAW
+
+   Write object *obj* to file object *p*.  The only supported flag for *flags* is
+   :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+   instead of the :func:`repr`.  Return ``0`` on success or ``-1`` on failure; the
+   appropriate exception will be set.
+
+
+.. c:function:: int PyFile_WriteString(const char *s, PyObject *p)
+
+   Write string *s* to file object *p*.  Return ``0`` on success or ``-1`` on
+   failure; the appropriate exception will be set.

third_party/python/Doc/c-api/float.rst

@@ -0,0 +1,79 @@
+.. highlightlang:: c
+
+.. _floatobjects:
+
+Floating Point Objects
+----------------------
+
+.. index:: object: floating point
+
+
+.. c:type:: PyFloatObject
+
+   This subtype of :c:type:`PyObject` represents a Python floating point object.
+
+
+.. c:var:: PyTypeObject PyFloat_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python floating point
+   type.  This is the same object as :class:`float` in the Python layer.
+
+
+.. c:function:: int PyFloat_Check(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyFloatObject` or a subtype of
+   :c:type:`PyFloatObject`.
+
+
+.. c:function:: int PyFloat_CheckExact(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyFloatObject`, but not a subtype of
+   :c:type:`PyFloatObject`.
+
+
+.. c:function:: PyObject* PyFloat_FromString(PyObject *str)
+
+   Create a :c:type:`PyFloatObject` object based on the string value in *str*, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyFloat_FromDouble(double v)
+
+   Create a :c:type:`PyFloatObject` object from *v*, or *NULL* on failure.
+
+
+.. c:function:: double PyFloat_AsDouble(PyObject *pyfloat)
+
+   Return a C :c:type:`double` representation of the contents of *pyfloat*.  If
+   *pyfloat* is not a Python floating point object but has a :meth:`__float__`
+   method, this method will first be called to convert *pyfloat* into a float.
+   This method returns ``-1.0`` upon failure, so one should call
+   :c:func:`PyErr_Occurred` to check for errors.
+
+
+.. c:function:: double PyFloat_AS_DOUBLE(PyObject *pyfloat)
+
+   Return a C :c:type:`double` representation of the contents of *pyfloat*, but
+   without error checking.
+
+
+.. c:function:: PyObject* PyFloat_GetInfo(void)
+
+   Return a structseq instance which contains information about the
+   precision, minimum and maximum values of a float. It's a thin wrapper
+   around the header file :file:`float.h`.
+
+
+.. c:function:: double PyFloat_GetMax()
+
+   Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`.
+
+
+.. c:function:: double PyFloat_GetMin()
+
+   Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`.
+
+.. c:function:: int PyFloat_ClearFreeList()
+
+   Clear the float free list. Return the number of items that could not
+   be freed.

third_party/python/Doc/c-api/function.rst

@@ -0,0 +1,108 @@
+.. highlightlang:: c
+
+.. _function-objects:
+
+Function Objects
+----------------
+
+.. index:: object: function
+
+There are a few functions specific to Python functions.
+
+
+.. c:type:: PyFunctionObject
+
+   The C structure used for functions.
+
+
+.. c:var:: PyTypeObject PyFunction_Type
+
+   .. index:: single: MethodType (in module types)
+
+   This is an instance of :c:type:`PyTypeObject` and represents the Python function
+   type.  It is exposed to Python programmers as ``types.FunctionType``.
+
+
+.. c:function:: int PyFunction_Check(PyObject *o)
+
+   Return true if *o* is a function object (has type :c:data:`PyFunction_Type`).
+   The parameter must not be *NULL*.
+
+
+.. c:function:: PyObject* PyFunction_New(PyObject *code, PyObject *globals)
+
+   Return a new function object associated with the code object *code*. *globals*
+   must be a dictionary with the global variables accessible to the function.
+
+   The function's docstring and name are retrieved from the code object. *__module__*
+   is retrieved from *globals*. The argument defaults, annotations and closure are
+   set to *NULL*. *__qualname__* is set to the same value as the function's name.
+
+
+.. c:function:: PyObject* PyFunction_NewWithQualName(PyObject *code, PyObject *globals, PyObject *qualname)
+
+   As :c:func:`PyFunction_New`, but also allows setting the function object's
+   ``__qualname__`` attribute.  *qualname* should be a unicode object or NULL;
+   if NULL, the ``__qualname__`` attribute is set to the same value as its
+   ``__name__`` attribute.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyFunction_GetCode(PyObject *op)
+
+   Return the code object associated with the function object *op*.
+
+
+.. c:function:: PyObject* PyFunction_GetGlobals(PyObject *op)
+
+   Return the globals dictionary associated with the function object *op*.
+
+
+.. c:function:: PyObject* PyFunction_GetModule(PyObject *op)
+
+   Return the *__module__* attribute of the function object *op*. This is normally
+   a string containing the module name, but can be set to any other object by
+   Python code.
+
+
+.. c:function:: PyObject* PyFunction_GetDefaults(PyObject *op)
+
+   Return the argument default values of the function object *op*. This can be a
+   tuple of arguments or *NULL*.
+
+
+.. c:function:: int PyFunction_SetDefaults(PyObject *op, PyObject *defaults)
+
+   Set the argument default values for the function object *op*. *defaults* must be
+   *Py_None* or a tuple.
+
+   Raises :exc:`SystemError` and returns ``-1`` on failure.
+
+
+.. c:function:: PyObject* PyFunction_GetClosure(PyObject *op)
+
+   Return the closure associated with the function object *op*. This can be *NULL*
+   or a tuple of cell objects.
+
+
+.. c:function:: int PyFunction_SetClosure(PyObject *op, PyObject *closure)
+
+   Set the closure associated with the function object *op*. *closure* must be
+   *Py_None* or a tuple of cell objects.
+
+   Raises :exc:`SystemError` and returns ``-1`` on failure.
+
+
+.. c:function:: PyObject *PyFunction_GetAnnotations(PyObject *op)
+
+   Return the annotations of the function object *op*. This can be a
+   mutable dictionary or *NULL*.
+
+
+.. c:function:: int PyFunction_SetAnnotations(PyObject *op, PyObject *annotations)
+
+   Set the annotations for the function object *op*. *annotations*
+   must be a dictionary or *Py_None*.
+
+   Raises :exc:`SystemError` and returns ``-1`` on failure.

third_party/python/Doc/c-api/gcsupport.rst

@@ -0,0 +1,159 @@
+.. highlightlang:: c
+
+.. _supporting-cycle-detection:
+
+Supporting Cyclic Garbage Collection
+====================================
+
+Python's support for detecting and collecting garbage which involves circular
+references requires support from object types which are "containers" for other
+objects which may also be containers.  Types which do not store references to
+other objects, or which only store references to atomic types (such as numbers
+or strings), do not need to provide any explicit support for garbage
+collection.
+
+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
+: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
+   :noindex:
+
+   Objects with a type with this flag set must conform with the rules
+   documented here.  For convenience these objects will be referred to as
+   container objects.
+
+Constructors for container types must conform to two rules:
+
+#. The memory for the object must be allocated using :c:func:`PyObject_GC_New`
+   or :c:func:`PyObject_GC_NewVar`.
+
+#. Once all the fields which may contain references to other containers are
+   initialized, it must call :c:func:`PyObject_GC_Track`.
+
+
+.. c:function:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)
+
+   Analogous to :c:func:`PyObject_New` but for container objects with the
+   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. c:function:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
+
+   Analogous to :c:func:`PyObject_NewVar` but for container objects with the
+   :const:`Py_TPFLAGS_HAVE_GC` flag set.
+
+
+.. c:function:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
+
+   Resize an object allocated by :c:func:`PyObject_NewVar`.  Returns the
+   resized object or *NULL* on failure.  *op* must not be tracked by the collector yet.
+
+
+.. c:function:: void PyObject_GC_Track(PyObject *op)
+
+   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 :c:member:`~PyTypeObject.tp_traverse` handler become valid, usually near the
+   end of the constructor.
+
+
+.. c:function:: void _PyObject_GC_TRACK(PyObject *op)
+
+   A macro version of :c:func:`PyObject_GC_Track`.  It should not be used for
+   extension modules.
+
+   .. deprecated:: 3.6
+      This macro is removed from Python 3.8.
+
+Similarly, the deallocator for the object must conform to a similar pair of
+rules:
+
+#. Before fields which refer to other containers are invalidated,
+   :c:func:`PyObject_GC_UnTrack` must be called.
+
+#. The object's memory must be deallocated using :c:func:`PyObject_GC_Del`.
+
+
+.. c:function:: void PyObject_GC_Del(void *op)
+
+   Releases memory allocated to an object using :c:func:`PyObject_GC_New` or
+   :c:func:`PyObject_GC_NewVar`.
+
+
+.. c:function:: void PyObject_GC_UnTrack(void *op)
+
+   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
+   (: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.
+
+   .. deprecated:: 3.6
+      This macro is removed from Python 3.8.
+
+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 :c:member:`~PyTypeObject.tp_traverse` handler.
+   The function should be called with an object to traverse as *object* and
+   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 :c:member:`~PyTypeObject.tp_traverse` handler must have the following type:
+
+
+.. c:type:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)
+
+   Traversal function for a container object.  Implementations must call the
+   *visit* function for each object directly contained by *self*, with the
+   parameters to *visit* being the contained object and the *arg* value passed
+   to the handler.  The *visit* function must not be called with a *NULL*
+   object argument.  If *visit* returns a non-zero value that value should be
+   returned immediately.
+
+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)
+
+   If *o* is not *NULL*, call the *visit* callback, with arguments *o*
+   and *arg*.  If *visit* returns a non-zero value, then return it.
+   Using this macro, :c:member:`~PyTypeObject.tp_traverse` handlers
+   look like::
+
+      static int
+      my_traverse(Noddy *self, visitproc visit, void *arg)
+      {
+          Py_VISIT(self->foo);
+          Py_VISIT(self->bar);
+          return 0;
+      }
+
+The :c:member:`~PyTypeObject.tp_clear` handler must be of the :c:type:`inquiry` type, or *NULL*
+if the object is immutable.
+
+
+.. c:type:: int (*inquiry)(PyObject *self)
+
+   Drop references that may have created reference cycles.  Immutable objects
+   do not have to define this method since they can never directly create
+   reference cycles.  Note that the object must still be valid after calling
+   this method (don't just call :c:func:`Py_DECREF` on a reference).  The
+   collector will call this method if it detects that this object is involved
+   in a reference cycle.

third_party/python/Doc/c-api/gen.rst

@@ -0,0 +1,44 @@
+.. highlightlang:: c
+
+.. _gen-objects:
+
+Generator Objects
+-----------------
+
+Generator objects are what Python uses to implement generator iterators. They
+are normally created by iterating over a function that yields values, rather
+than explicitly calling :c:func:`PyGen_New` or :c:func:`PyGen_NewWithQualName`.
+
+
+.. c:type:: PyGenObject
+
+   The C structure used for generator objects.
+
+
+.. c:var:: PyTypeObject PyGen_Type
+
+   The type object corresponding to generator objects.
+
+
+.. c:function:: int PyGen_Check(PyObject *ob)
+
+   Return true if *ob* is a generator object; *ob* must not be *NULL*.
+
+
+.. c:function:: int PyGen_CheckExact(PyObject *ob)
+
+   Return true if *ob*'s type is *PyGen_Type*; *ob* must not be *NULL*.
+
+
+.. c:function:: PyObject* PyGen_New(PyFrameObject *frame)
+
+   Create and return a new generator object based on the *frame* object.
+   A reference to *frame* is stolen by this function. The argument must not be
+   *NULL*.
+
+.. c:function:: PyObject* PyGen_NewWithQualName(PyFrameObject *frame, PyObject *name, PyObject *qualname)
+
+   Create and return a new generator object based on the *frame* object,
+   with ``__name__`` and ``__qualname__`` set to *name* and *qualname*.
+   A reference to *frame* is stolen by this function.  The *frame* argument
+   must not be *NULL*.

third_party/python/Doc/c-api/import.rst

@@ -0,0 +1,315 @@
+.. highlightlang:: c
+
+.. _importing:
+
+Importing Modules
+=================
+
+
+.. c:function:: PyObject* PyImport_ImportModule(const char *name)
+
+   .. index::
+      single: package variable; __all__
+      single: __all__ (package variable)
+      single: modules (in module sys)
+
+   This is a simplified interface to :c:func:`PyImport_ImportModuleEx` below,
+   leaving the *globals* and *locals* arguments set to *NULL* and *level* set
+   to 0.  When the *name*
+   argument contains a dot (when it specifies a submodule of a package), the
+   *fromlist* argument is set to the list ``['*']`` so that the return value is the
+   named module rather than the top-level package containing it as would otherwise
+   be the case.  (Unfortunately, this has an additional side effect when *name* in
+   fact specifies a subpackage instead of a submodule: the submodules specified in
+   the package's ``__all__`` variable are  loaded.)  Return a new reference to the
+   imported module, or *NULL* with an exception set on failure.  A failing
+   import of a module doesn't leave the module in :data:`sys.modules`.
+
+   This function always uses absolute imports.
+
+
+.. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name)
+
+   This function is a deprecated alias of :c:func:`PyImport_ImportModule`.
+
+   .. versionchanged:: 3.3
+      This function used to fail immediately when the import lock was held
+      by another thread.  In Python 3.3 though, the locking scheme switched
+      to per-module locks for most purposes, so this function's special
+      behaviour isn't needed anymore.
+
+
+.. c:function:: PyObject* PyImport_ImportModuleEx(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist)
+
+   .. index:: builtin: __import__
+
+   Import a module.  This is best described by referring to the built-in Python
+   function :func:`__import__`.
+
+   The return value is a new reference to the imported module or top-level
+   package, or *NULL* with an exception set on failure.  Like for
+   :func:`__import__`, the return value when a submodule of a package was
+   requested is normally the top-level package, unless a non-empty *fromlist*
+   was given.
+
+   Failing imports remove incomplete module objects, like with
+   :c:func:`PyImport_ImportModule`.
+
+
+.. c:function:: PyObject* PyImport_ImportModuleLevelObject(PyObject *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
+
+   Import a module.  This is best described by referring to the built-in Python
+   function :func:`__import__`, as the standard :func:`__import__` function calls
+   this function directly.
+
+   The return value is a new reference to the imported module or top-level package,
+   or *NULL* with an exception set on failure.  Like for :func:`__import__`,
+   the return value when a submodule of a package was requested is normally the
+   top-level package, unless a non-empty *fromlist* was given.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyImport_ImportModuleLevel(const char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)
+
+   Similar to :c:func:`PyImport_ImportModuleLevelObject`, but the name is a
+   UTF-8 encoded string instead of a Unicode object.
+
+   .. versionchanged:: 3.3
+         Negative values for *level* are no longer accepted.
+
+.. c:function:: PyObject* PyImport_Import(PyObject *name)
+
+   This is a higher-level interface that calls the current "import hook
+   function" (with an explicit *level* of 0, meaning absolute import).  It
+   invokes the :func:`__import__` function from the ``__builtins__`` of the
+   current globals.  This means that the import is done using whatever import
+   hooks are installed in the current environment.
+
+   This function always uses absolute imports.
+
+
+.. c:function:: PyObject* PyImport_ReloadModule(PyObject *m)
+
+   Reload a module.  Return a new reference to the reloaded module, or *NULL* with
+   an exception set on failure (the module still exists in this case).
+
+
+.. c:function:: PyObject* PyImport_AddModuleObject(PyObject *name)
+
+   Return the module object corresponding to a module name.  The *name* argument
+   may be of the form ``package.module``. First check the modules dictionary if
+   there's one there, and if not, create a new one and insert it in the modules
+   dictionary. Return *NULL* with an exception set on failure.
+
+   .. note::
+
+      This function does not load or import the module; if the module wasn't already
+      loaded, you will get an empty module object. Use :c:func:`PyImport_ImportModule`
+      or one of its variants to import a module.  Package structures implied by a
+      dotted name for *name* are not created if not already present.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyImport_AddModule(const char *name)
+
+   Similar to :c:func:`PyImport_AddModuleObject`, but the name is a UTF-8
+   encoded string instead of a Unicode object.
+
+
+.. c:function:: PyObject* PyImport_ExecCodeModule(const char *name, PyObject *co)
+
+   .. index:: builtin: compile
+
+   Given a module name (possibly of the form ``package.module``) and a code object
+   read from a Python bytecode file or obtained from the built-in function
+   :func:`compile`, load the module.  Return a new reference to the module object,
+   or *NULL* with an exception set if an error occurred.  *name*
+   is removed from :attr:`sys.modules` in error cases, even if *name* was already
+   in :attr:`sys.modules` on entry to :c:func:`PyImport_ExecCodeModule`.  Leaving
+   incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of
+   such modules have no way to know that the module object is an unknown (and
+   probably damaged with respect to the module author's intents) state.
+
+   The module's :attr:`__spec__` and :attr:`__loader__` will be set, if
+   not set already, with the appropriate values.  The spec's loader will
+   be set to the module's ``__loader__`` (if set) and to an instance of
+   :class:`SourceFileLoader` otherwise.
+
+   The module's :attr:`__file__` attribute will be set to the code object's
+   :c:member:`co_filename`.  If applicable, :attr:`__cached__` will also
+   be set.
+
+   This function will reload the module if it was already imported.  See
+   :c:func:`PyImport_ReloadModule` for the intended way to reload a module.
+
+   If *name* points to a dotted name of the form ``package.module``, any package
+   structures not already created will still not be created.
+
+   See also :c:func:`PyImport_ExecCodeModuleEx` and
+   :c:func:`PyImport_ExecCodeModuleWithPathnames`.
+
+
+.. c:function:: PyObject* PyImport_ExecCodeModuleEx(const char *name, PyObject *co, const char *pathname)
+
+   Like :c:func:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of
+   the module object is set to *pathname* if it is non-``NULL``.
+
+   See also :c:func:`PyImport_ExecCodeModuleWithPathnames`.
+
+
+.. c:function:: PyObject* PyImport_ExecCodeModuleObject(PyObject *name, PyObject *co, PyObject *pathname, PyObject *cpathname)
+
+   Like :c:func:`PyImport_ExecCodeModuleEx`, but the :attr:`__cached__`
+   attribute of the module object is set to *cpathname* if it is
+   non-``NULL``.  Of the three functions, this is the preferred one to use.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyImport_ExecCodeModuleWithPathnames(const char *name, PyObject *co, const char *pathname, const char *cpathname)
+
+   Like :c:func:`PyImport_ExecCodeModuleObject`, but *name*, *pathname* and
+   *cpathname* are UTF-8 encoded strings. Attempts are also made to figure out
+   what the value for *pathname* should be from *cpathname* if the former is
+   set to ``NULL``.
+
+   .. versionadded:: 3.2
+   .. versionchanged:: 3.3
+      Uses :func:`imp.source_from_cache()` in calculating the source path if
+      only the bytecode path is provided.
+
+
+.. c:function:: long PyImport_GetMagicNumber()
+
+   Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` file).
+   The magic number should be present in the first four bytes of the bytecode
+   file, in little-endian byte order. Returns ``-1`` on error.
+
+   .. versionchanged:: 3.3
+      Return value of ``-1`` upon failure.
+
+
+.. c:function:: const char * PyImport_GetMagicTag()
+
+   Return the magic tag string for :pep:`3147` format Python bytecode file
+   names.  Keep in mind that the value at ``sys.implementation.cache_tag`` is
+   authoritative and should be used instead of this function.
+
+   .. versionadded:: 3.2
+
+.. c:function:: PyObject* PyImport_GetModuleDict()
+
+   Return the dictionary used for the module administration (a.k.a.
+   ``sys.modules``).  Note that this is a per-interpreter variable.
+
+
+.. c:function:: PyObject* PyImport_GetImporter(PyObject *path)
+
+   Return a finder object for a :data:`sys.path`/:attr:`pkg.__path__` item
+   *path*, possibly by fetching it from the :data:`sys.path_importer_cache`
+   dict.  If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook
+   is found that can handle the path item.  Return ``None`` if no hook could;
+   this tells our caller that the :term:`path based finder` could not find a
+   finder for this path item. Cache the result in :data:`sys.path_importer_cache`.
+   Return a new reference to the finder object.
+
+
+.. c:function:: void _PyImport_Init()
+
+   Initialize the import mechanism.  For internal use only.
+
+
+.. c:function:: void PyImport_Cleanup()
+
+   Empty the module table.  For internal use only.
+
+
+.. c:function:: void _PyImport_Fini()
+
+   Finalize the import mechanism.  For internal use only.
+
+
+.. c:function:: PyObject* _PyImport_FindExtension(char *, char *)
+
+   For internal use only.
+
+
+.. c:function:: int PyImport_ImportFrozenModuleObject(PyObject *name)
+
+   Load a frozen module named *name*.  Return ``1`` for success, ``0`` if the
+   module is not found, and ``-1`` with an exception set if the initialization
+   failed.  To access the imported module on a successful load, use
+   :c:func:`PyImport_ImportModule`.  (Note the misnomer --- this function would
+   reload the module if it was already imported.)
+
+   .. versionadded:: 3.3
+
+   .. versionchanged:: 3.4
+      The ``__file__`` attribute is no longer set on the module.
+
+
+.. c:function:: int PyImport_ImportFrozenModule(const char *name)
+
+   Similar to :c:func:`PyImport_ImportFrozenModuleObject`, but the name is a
+   UTF-8 encoded string instead of a Unicode object.
+
+
+.. c:type:: struct _frozen
+
+   .. index:: single: freeze utility
+
+   This is the structure type definition for frozen module descriptors, as
+   generated by the :program:`freeze` utility (see :file:`Tools/freeze/` in the
+   Python source distribution).  Its definition, found in :file:`Include/import.h`,
+   is::
+
+      struct _frozen {
+          char *name;
+          unsigned char *code;
+          int size;
+      };
+
+
+.. c:var:: const struct _frozen* PyImport_FrozenModules
+
+   This pointer is initialized to point to an array of :c:type:`struct _frozen`
+   records, terminated by one whose members are all *NULL* or zero.  When a frozen
+   module is imported, it is searched in this table.  Third-party code could play
+   tricks with this to provide a dynamically created collection of frozen modules.
+
+
+.. c:function:: int PyImport_AppendInittab(const char *name, PyObject* (*initfunc)(void))
+
+   Add a single module to the existing table of built-in modules.  This is a
+   convenience wrapper around :c:func:`PyImport_ExtendInittab`, returning ``-1`` if
+   the table could not be extended.  The new module can be imported by the name
+   *name*, and uses the function *initfunc* as the initialization function called
+   on the first attempted import.  This should be called before
+   :c:func:`Py_Initialize`.
+
+
+.. c:type:: struct _inittab
+
+   Structure describing a single entry in the list of built-in modules.  Each of
+   these structures gives the name and initialization function for a module built
+   into the interpreter.  The name is an ASCII encoded string.  Programs which
+   embed Python may use an array of these structures in conjunction with
+   :c:func:`PyImport_ExtendInittab` to provide additional built-in modules.
+   The structure is defined in :file:`Include/import.h` as::
+
+      struct _inittab {
+          char *name;                 /* ASCII encoded string */
+          PyObject* (*initfunc)(void);
+      };
+
+
+.. c:function:: int PyImport_ExtendInittab(struct _inittab *newtab)
+
+   Add a collection of modules to the table of built-in modules.  The *newtab*
+   array must end with a sentinel entry which contains *NULL* for the :attr:`name`
+   field; failure to provide the sentinel value can result in a memory fault.
+   Returns ``0`` on success or ``-1`` if insufficient memory could be allocated to
+   extend the internal table.  In the event of failure, no modules are added to the
+   internal table.  This should be called before :c:func:`Py_Initialize`.

third_party/python/Doc/c-api/index.rst

@@ -0,0 +1,26 @@
+.. _c-api-index:
+
+##################################
+  Python/C API Reference Manual
+##################################
+
+This manual documents the API used by C and C++ programmers who want to write
+extension modules or embed Python.  It is a companion to :ref:`extending-index`,
+which describes the general principles of extension writing but does not
+document the API functions in detail.
+
+.. toctree::
+   :maxdepth: 2
+
+   intro.rst
+   stable.rst
+   veryhigh.rst
+   refcounting.rst
+   exceptions.rst
+   utilities.rst
+   abstract.rst
+   concrete.rst
+   init.rst
+   memory.rst
+   objimpl.rst
+   apiabiversion.rst

third_party/python/Doc/c-api/intro.rst

@@ -0,0 +1,645 @@
+.. highlightlang:: c
+
+
+.. _api-intro:
+
+************
+Introduction
+************
+
+The Application Programmer's Interface to Python gives C and C++ programmers
+access to the Python interpreter at a variety of levels.  The API is equally
+usable from C++, but for brevity it is generally referred to as the Python/C
+API.  There are two fundamentally different reasons for using the Python/C API.
+The first reason is to write *extension modules* for specific purposes; these
+are C modules that extend the Python interpreter.  This is probably the most
+common use.  The second reason is to use Python as a component in a larger
+application; this technique is generally referred to as :dfn:`embedding` Python
+in an application.
+
+Writing an extension module is a relatively well-understood process,  where a
+"cookbook" approach works well.  There are several tools  that automate the
+process to some extent.  While people have embedded  Python in other
+applications since its early existence, the process of  embedding Python is less
+straightforward than writing an extension.
+
+Many API functions are useful independent of whether you're embedding  or
+extending Python; moreover, most applications that embed Python  will need to
+provide a custom extension as well, so it's probably a  good idea to become
+familiar with writing an extension before  attempting to embed Python in a real
+application.
+
+
+.. _api-includes:
+
+Include Files
+=============
+
+All function, type and macro definitions needed to use the Python/C API are
+included in your code by the following line::
+
+   #include "Python.h"
+
+This implies inclusion of the following standard headers: ``<stdio.h>``,
+``<string.h>``, ``<errno.h>``, ``<limits.h>``, ``<assert.h>`` and ``<stdlib.h>``
+(if available).
+
+.. note::
+
+   Since Python may define some pre-processor definitions which affect the standard
+   headers on some systems, you *must* include :file:`Python.h` before any standard
+   headers are included.
+
+All user visible names defined by Python.h (except those defined by the included
+standard headers) have one of the prefixes ``Py`` or ``_Py``.  Names beginning
+with ``_Py`` are for internal use by the Python implementation and should not be
+used by extension writers. Structure member names do not have a reserved prefix.
+
+**Important:** user code should never define names that begin with ``Py`` or
+``_Py``.  This confuses the reader, and jeopardizes the portability of the user
+code to future Python versions, which may define additional names beginning with
+one of these prefixes.
+
+The header files are typically installed with Python.  On Unix, these  are
+located in the directories :file:`{prefix}/include/pythonversion/` and
+:file:`{exec_prefix}/include/pythonversion/`, where :envvar:`prefix` and
+:envvar:`exec_prefix` are defined by the corresponding parameters to Python's
+:program:`configure` script and *version* is
+``'%d.%d' % sys.version_info[:2]``.  On Windows, the headers are installed
+in :file:`{prefix}/include`, where :envvar:`prefix` is the installation
+directory specified to the installer.
+
+To include the headers, place both directories (if different) on your compiler's
+search path for includes.  Do *not* place the parent directories on the search
+path and then use ``#include <pythonX.Y/Python.h>``; this will break on
+multi-platform builds since the platform independent headers under
+:envvar:`prefix` include the platform specific headers from
+:envvar:`exec_prefix`.
+
+C++ users should note that though the API is defined entirely using C, the
+header files do properly declare the entry points to be ``extern "C"``, so there
+is no need to do anything special to use the API from C++.
+
+
+.. _api-objects:
+
+Objects, Types and Reference Counts
+===================================
+
+.. index:: object: type
+
+Most Python/C API functions have one or more arguments as well as a return value
+of type :c:type:`PyObject\*`.  This type is a pointer to an opaque data type
+representing an arbitrary Python object.  Since all Python object types are
+treated the same way by the Python language in most situations (e.g.,
+assignments, scope rules, and argument passing), it is only fitting that they
+should be represented by a single C type.  Almost all Python objects live on the
+heap: you never declare an automatic or static variable of type
+:c:type:`PyObject`, only pointer variables of type :c:type:`PyObject\*` can  be
+declared.  The sole exception are the type objects; since these must never be
+deallocated, they are typically static :c:type:`PyTypeObject` objects.
+
+All Python objects (even Python integers) have a :dfn:`type` and a
+:dfn:`reference count`.  An object's type determines what kind of object it is
+(e.g., an integer, a list, or a user-defined function; there are many more as
+explained in :ref:`types`).  For each of the well-known types there is a macro
+to check whether an object is of that type; for instance, ``PyList_Check(a)`` is
+true if (and only if) the object pointed to by *a* is a Python list.
+
+
+.. _api-refcounts:
+
+Reference Counts
+----------------
+
+The reference count is important because today's computers have a  finite (and
+often severely limited) memory size; it counts how many  different places there
+are that have a reference to an object.  Such a  place could be another object,
+or a global (or static) C variable, or  a local variable in some C function.
+When an object's reference count  becomes zero, the object is deallocated.  If
+it contains references to  other objects, their reference count is decremented.
+Those other  objects may be deallocated in turn, if this decrement makes their
+reference count become zero, and so on.  (There's an obvious problem  with
+objects that reference each other here; for now, the solution is  "don't do
+that.")
+
+.. index::
+   single: Py_INCREF()
+   single: Py_DECREF()
+
+Reference counts are always manipulated explicitly.  The normal way is  to use
+the macro :c:func:`Py_INCREF` to increment an object's reference count by one,
+and :c:func:`Py_DECREF` to decrement it by   one.  The :c:func:`Py_DECREF` macro
+is considerably more complex than the incref one, since it must check whether
+the reference count becomes zero and then cause the object's deallocator to be
+called. The deallocator is a function pointer contained in the object's type
+structure.  The type-specific deallocator takes care of decrementing the
+reference counts for other objects contained in the object if this is a compound
+object type, such as a list, as well as performing any additional finalization
+that's needed.  There's no chance that the reference count can overflow; at
+least as many bits are used to hold the reference count as there are distinct
+memory locations in virtual memory (assuming ``sizeof(Py_ssize_t) >= sizeof(void*)``).
+Thus, the reference count increment is a simple operation.
+
+It is not necessary to increment an object's reference count for every  local
+variable that contains a pointer to an object.  In theory, the  object's
+reference count goes up by one when the variable is made to  point to it and it
+goes down by one when the variable goes out of  scope.  However, these two
+cancel each other out, so at the end the  reference count hasn't changed.  The
+only real reason to use the  reference count is to prevent the object from being
+deallocated as  long as our variable is pointing to it.  If we know that there
+is at  least one other reference to the object that lives at least as long as
+our variable, there is no need to increment the reference count  temporarily.
+An important situation where this arises is in objects  that are passed as
+arguments to C functions in an extension module  that are called from Python;
+the call mechanism guarantees to hold a  reference to every argument for the
+duration of the call.
+
+However, a common pitfall is to extract an object from a list and hold on to it
+for a while without incrementing its reference count. Some other operation might
+conceivably remove the object from the list, decrementing its reference count
+and possible deallocating it. The real danger is that innocent-looking
+operations may invoke arbitrary Python code which could do this; there is a code
+path which allows control to flow back to the user from a :c:func:`Py_DECREF`, so
+almost any operation is potentially dangerous.
+
+A safe approach is to always use the generic operations (functions  whose name
+begins with ``PyObject_``, ``PyNumber_``, ``PySequence_`` or ``PyMapping_``).
+These operations always increment the reference count of the object they return.
+This leaves the caller with the responsibility to call :c:func:`Py_DECREF` when
+they are done with the result; this soon becomes second nature.
+
+
+.. _api-refcountdetails:
+
+Reference Count Details
+^^^^^^^^^^^^^^^^^^^^^^^
+
+The reference count behavior of functions in the Python/C API is best  explained
+in terms of *ownership of references*.  Ownership pertains to references, never
+to objects (objects are not owned: they are always shared).  "Owning a
+reference" means being responsible for calling Py_DECREF on it when the
+reference is no longer needed.  Ownership can also be transferred, meaning that
+the code that receives ownership of the reference then becomes responsible for
+eventually decref'ing it by calling :c:func:`Py_DECREF` or :c:func:`Py_XDECREF`
+when it's no longer needed---or passing on this responsibility (usually to its
+caller). When a function passes ownership of a reference on to its caller, the
+caller is said to receive a *new* reference.  When no ownership is transferred,
+the caller is said to *borrow* the reference. Nothing needs to be done for a
+borrowed reference.
+
+Conversely, when a calling function passes in a reference to an  object, there
+are two possibilities: the function *steals* a  reference to the object, or it
+does not.  *Stealing a reference* means that when you pass a reference to a
+function, that function assumes that it now owns that reference, and you are not
+responsible for it any longer.
+
+.. index::
+   single: PyList_SetItem()
+   single: PyTuple_SetItem()
+
+Few functions steal references; the two notable exceptions are
+:c:func:`PyList_SetItem` and :c:func:`PyTuple_SetItem`, which  steal a reference
+to the item (but not to the tuple or list into which the item is put!).  These
+functions were designed to steal a reference because of a common idiom for
+populating a tuple or list with newly created objects; for example, the code to
+create the tuple ``(1, 2, "three")`` could look like this (forgetting about
+error handling for the moment; a better way to code this is shown below)::
+
+   PyObject *t;
+
+   t = PyTuple_New(3);
+   PyTuple_SetItem(t, 0, PyLong_FromLong(1L));
+   PyTuple_SetItem(t, 1, PyLong_FromLong(2L));
+   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
+although the reference to it will be stolen, use :c:func:`Py_INCREF` to grab
+another reference before calling the reference-stealing function.
+
+Incidentally, :c:func:`PyTuple_SetItem` is the *only* way to set tuple items;
+:c:func:`PySequence_SetItem` and :c:func:`PyObject_SetItem` refuse to do this
+since tuples are an immutable data type.  You should only use
+:c:func:`PyTuple_SetItem` for tuples that you are creating yourself.
+
+Equivalent code for populating a list can be written using :c:func:`PyList_New`
+and :c:func:`PyList_SetItem`.
+
+However, in practice, you will rarely use these ways of creating and populating
+a tuple or list.  There's a generic function, :c:func:`Py_BuildValue`, that can
+create most common objects from C values, directed by a :dfn:`format string`.
+For example, the above two blocks of code could be replaced by the following
+(which also takes care of the error checking)::
+
+   PyObject *tuple, *list;
+
+   tuple = Py_BuildValue("(iis)", 1, 2, "three");
+   list = Py_BuildValue("[iis]", 1, 2, "three");
+
+It is much more common to use :c:func:`PyObject_SetItem` and friends with items
+whose references you are only borrowing, like arguments that were passed in to
+the function you are writing.  In that case, their behaviour regarding reference
+counts is much saner, since you don't have to increment a reference count so you
+can give a reference away ("have it be stolen").  For example, this function
+sets all items of a list (actually, any mutable sequence) to a given item::
+
+   int
+   set_all(PyObject *target, PyObject *item)
+   {
+       Py_ssize_t i, n;
+
+       n = PyObject_Length(target);
+       if (n < 0)
+           return -1;
+       for (i = 0; i < n; i++) {
+           PyObject *index = PyLong_FromSsize_t(i);
+           if (!index)
+               return -1;
+           if (PyObject_SetItem(target, index, item) < 0) {
+               Py_DECREF(index);
+               return -1;
+           }
+           Py_DECREF(index);
+       }
+       return 0;
+   }
+
+.. index:: single: set_all()
+
+The situation is slightly different for function return values.   While passing
+a reference to most functions does not change your  ownership responsibilities
+for that reference, many functions that  return a reference to an object give
+you ownership of the reference. The reason is simple: in many cases, the
+returned object is created  on the fly, and the reference you get is the only
+reference to the  object.  Therefore, the generic functions that return object
+references, like :c:func:`PyObject_GetItem` and  :c:func:`PySequence_GetItem`,
+always return a new reference (the caller becomes the owner of the reference).
+
+It is important to realize that whether you own a reference returned  by a
+function depends on which function you call only --- *the plumage* (the type of
+the object passed as an argument to the function) *doesn't enter into it!*
+Thus, if you  extract an item from a list using :c:func:`PyList_GetItem`, you
+don't own the reference --- but if you obtain the same item from the same list
+using :c:func:`PySequence_GetItem` (which happens to take exactly the same
+arguments), you do own a reference to the returned object.
+
+.. index::
+   single: PyList_GetItem()
+   single: PySequence_GetItem()
+
+Here is an example of how you could write a function that computes the sum of
+the items in a list of integers; once using  :c:func:`PyList_GetItem`, and once
+using :c:func:`PySequence_GetItem`. ::
+
+   long
+   sum_list(PyObject *list)
+   {
+       Py_ssize_t i, n;
+       long total = 0, value;
+       PyObject *item;
+
+       n = PyList_Size(list);
+       if (n < 0)
+           return -1; /* Not a list */
+       for (i = 0; i < n; i++) {
+           item = PyList_GetItem(list, i); /* Can't fail */
+           if (!PyLong_Check(item)) continue; /* Skip non-integers */
+           value = PyLong_AsLong(item);
+           if (value == -1 && PyErr_Occurred())
+               /* Integer too big to fit in a C long, bail out */
+               return -1;
+           total += value;
+       }
+       return total;
+   }
+
+.. index:: single: sum_list()
+
+::
+
+   long
+   sum_sequence(PyObject *sequence)
+   {
+       Py_ssize_t i, n;
+       long total = 0, value;
+       PyObject *item;
+       n = PySequence_Length(sequence);
+       if (n < 0)
+           return -1; /* Has no length */
+       for (i = 0; i < n; i++) {
+           item = PySequence_GetItem(sequence, i);
+           if (item == NULL)
+               return -1; /* Not a sequence, or other failure */
+           if (PyLong_Check(item)) {
+               value = PyLong_AsLong(item);
+               Py_DECREF(item);
+               if (value == -1 && PyErr_Occurred())
+                   /* Integer too big to fit in a C long, bail out */
+                   return -1;
+               total += value;
+           }
+           else {
+               Py_DECREF(item); /* Discard reference ownership */
+           }
+       }
+       return total;
+   }
+
+.. index:: single: sum_sequence()
+
+
+.. _api-types:
+
+Types
+-----
+
+There are few other data types that play a significant role in  the Python/C
+API; most are simple C types such as :c:type:`int`,  :c:type:`long`,
+:c:type:`double` and :c:type:`char\*`.  A few structure types  are used to
+describe static tables used to list the functions exported  by a module or the
+data attributes of a new object type, and another is used to describe the value
+of a complex number.  These will  be discussed together with the functions that
+use them.
+
+
+.. _api-exceptions:
+
+Exceptions
+==========
+
+The Python programmer only needs to deal with exceptions if specific  error
+handling is required; unhandled exceptions are automatically  propagated to the
+caller, then to the caller's caller, and so on, until they reach the top-level
+interpreter, where they are reported to the  user accompanied by a stack
+traceback.
+
+.. index:: single: PyErr_Occurred()
+
+For C programmers, however, error checking always has to be explicit.  All
+functions in the Python/C API can raise exceptions, unless an explicit claim is
+made otherwise in a function's documentation.  In general, when a function
+encounters an error, it sets an exception, discards any object references that
+it owns, and returns an error indicator.  If not documented otherwise, this
+indicator is either *NULL* or ``-1``, depending on the function's return type.
+A few functions return a Boolean true/false result, with false indicating an
+error.  Very few functions return no explicit error indicator or have an
+ambiguous return value, and require explicit testing for errors with
+:c:func:`PyErr_Occurred`.  These exceptions are always explicitly documented.
+
+.. index::
+   single: PyErr_SetString()
+   single: PyErr_Clear()
+
+Exception state is maintained in per-thread storage (this is  equivalent to
+using global storage in an unthreaded application).  A  thread can be in one of
+two states: an exception has occurred, or not. The function
+:c:func:`PyErr_Occurred` can be used to check for this: it returns a borrowed
+reference to the exception type object when an exception has occurred, and
+*NULL* otherwise.  There are a number of functions to set the exception state:
+:c:func:`PyErr_SetString` is the most common (though not the most general)
+function to set the exception state, and :c:func:`PyErr_Clear` clears the
+exception state.
+
+The full exception state consists of three objects (all of which can  be
+*NULL*): the exception type, the corresponding exception  value, and the
+traceback.  These have the same meanings as the Python result of
+``sys.exc_info()``; however, they are not the same: the Python objects represent
+the last exception being handled by a Python  :keyword:`try` ...
+:keyword:`except` statement, while the C level exception state only exists while
+an exception is being passed on between C functions until it reaches the Python
+bytecode interpreter's  main loop, which takes care of transferring it to
+``sys.exc_info()`` and friends.
+
+.. index:: single: exc_info() (in module sys)
+
+Note that starting with Python 1.5, the preferred, thread-safe way to access the
+exception state from Python code is to call the function :func:`sys.exc_info`,
+which returns the per-thread exception state for Python code.  Also, the
+semantics of both ways to access the exception state have changed so that a
+function which catches an exception will save and restore its thread's exception
+state so as to preserve the exception state of its caller.  This prevents common
+bugs in exception handling code caused by an innocent-looking function
+overwriting the exception being handled; it also reduces the often unwanted
+lifetime extension for objects that are referenced by the stack frames in the
+traceback.
+
+As a general principle, a function that calls another function to  perform some
+task should check whether the called function raised an  exception, and if so,
+pass the exception state on to its caller.  It  should discard any object
+references that it owns, and return an  error indicator, but it should *not* set
+another exception --- that would overwrite the exception that was just raised,
+and lose important information about the exact cause of the error.
+
+.. 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 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::
+
+   def incr_item(dict, key):
+       try:
+           item = dict[key]
+       except KeyError:
+           item = 0
+       dict[key] = item + 1
+
+.. index:: single: incr_item()
+
+Here is the corresponding C code, in all its glory::
+
+   int
+   incr_item(PyObject *dict, PyObject *key)
+   {
+       /* Objects all initialized to NULL for Py_XDECREF */
+       PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
+       int rv = -1; /* Return value initialized to -1 (failure) */
+
+       item = PyObject_GetItem(dict, key);
+       if (item == NULL) {
+           /* Handle KeyError only: */
+           if (!PyErr_ExceptionMatches(PyExc_KeyError))
+               goto error;
+
+           /* Clear the error and use zero: */
+           PyErr_Clear();
+           item = PyLong_FromLong(0L);
+           if (item == NULL)
+               goto error;
+       }
+       const_one = PyLong_FromLong(1L);
+       if (const_one == NULL)
+           goto error;
+
+       incremented_item = PyNumber_Add(item, const_one);
+       if (incremented_item == NULL)
+           goto error;
+
+       if (PyObject_SetItem(dict, key, incremented_item) < 0)
+           goto error;
+       rv = 0; /* Success */
+       /* Continue with cleanup code */
+
+    error:
+       /* Cleanup code, shared by success and failure path */
+
+       /* Use Py_XDECREF() to ignore NULL references */
+       Py_XDECREF(item);
+       Py_XDECREF(const_one);
+       Py_XDECREF(incremented_item);
+
+       return rv; /* -1 for error, 0 for success */
+   }
+
+.. index:: single: incr_item()
+
+.. index::
+   single: PyErr_ExceptionMatches()
+   single: PyErr_Clear()
+   single: Py_XDECREF()
+
+This example represents an endorsed use of the ``goto`` statement  in C!
+It illustrates the use of :c:func:`PyErr_ExceptionMatches` and
+:c:func:`PyErr_Clear` to handle specific exceptions, and the use of
+:c:func:`Py_XDECREF` to dispose of owned references that may be *NULL* (note the
+``'X'`` in the name; :c:func:`Py_DECREF` would crash when confronted with a
+*NULL* reference).  It is important that the variables used to hold owned
+references are initialized to *NULL* for this to work; likewise, the proposed
+return value is initialized to ``-1`` (failure) and only set to success after
+the final call made is successful.
+
+
+.. _api-embedding:
+
+Embedding Python
+================
+
+The one important task that only embedders (as opposed to extension writers) of
+the Python interpreter have to worry about is the initialization, and possibly
+the finalization, of the Python interpreter.  Most functionality of the
+interpreter can only be used after the interpreter has been initialized.
+
+.. index::
+   single: Py_Initialize()
+   module: builtins
+   module: __main__
+   module: sys
+   triple: module; search; path
+   single: path (in module sys)
+
+The basic initialization function is :c:func:`Py_Initialize`. This initializes
+the table of loaded modules, and creates the fundamental modules
+:mod:`builtins`, :mod:`__main__`, and :mod:`sys`.  It also
+initializes the module search path (``sys.path``).
+
+.. index:: single: PySys_SetArgvEx()
+
+:c:func:`Py_Initialize` does not set the "script argument list"  (``sys.argv``).
+If this variable is needed by Python code that will be executed later, it must
+be set explicitly with a call to  ``PySys_SetArgvEx(argc, argv, updatepath)``
+after the call to :c:func:`Py_Initialize`.
+
+On most systems (in particular, on Unix and Windows, although the details are
+slightly different), :c:func:`Py_Initialize` calculates the module search path
+based upon its best guess for the location of the standard Python interpreter
+executable, assuming that the Python library is found in a fixed location
+relative to the Python interpreter executable.  In particular, it looks for a
+directory named :file:`lib/python{X.Y}` relative to the parent directory
+where the executable named :file:`python` is found on the shell command search
+path (the environment variable :envvar:`PATH`).
+
+For instance, if the Python executable is found in
+:file:`/usr/local/bin/python`, it will assume that the libraries are in
+:file:`/usr/local/lib/python{X.Y}`.  (In fact, this particular path is also
+the "fallback" location, used when no executable file named :file:`python` is
+found along :envvar:`PATH`.)  The user can override this behavior by setting the
+environment variable :envvar:`PYTHONHOME`, or insert additional directories in
+front of the standard path by setting :envvar:`PYTHONPATH`.
+
+.. index::
+   single: Py_SetProgramName()
+   single: Py_GetPath()
+   single: Py_GetPrefix()
+   single: Py_GetExecPrefix()
+   single: Py_GetProgramFullPath()
+
+The embedding application can steer the search by calling
+``Py_SetProgramName(file)`` *before* calling  :c:func:`Py_Initialize`.  Note that
+:envvar:`PYTHONHOME` still overrides this and :envvar:`PYTHONPATH` is still
+inserted in front of the standard path.  An application that requires total
+control has to provide its own implementation of :c:func:`Py_GetPath`,
+:c:func:`Py_GetPrefix`, :c:func:`Py_GetExecPrefix`, and
+:c:func:`Py_GetProgramFullPath` (all defined in :file:`Modules/getpath.c`).
+
+.. index:: single: Py_IsInitialized()
+
+Sometimes, it is desirable to "uninitialize" Python.  For instance,  the
+application may want to start over (make another call to
+:c:func:`Py_Initialize`) or the application is simply done with its  use of
+Python and wants to free memory allocated by Python.  This can be accomplished
+by calling :c:func:`Py_FinalizeEx`.  The function :c:func:`Py_IsInitialized` returns
+true if Python is currently in the initialized state.  More information about
+these functions is given in a later chapter. Notice that :c:func:`Py_FinalizeEx`
+does *not* free all memory allocated by the Python interpreter, e.g. memory
+allocated by extension modules currently cannot be released.
+
+
+.. _api-debugging:
+
+Debugging Builds
+================
+
+Python can be built with several macros to enable extra checks of the
+interpreter and extension modules.  These checks tend to add a large amount of
+overhead to the runtime so they are not enabled by default.
+
+A full list of the various types of debugging builds is in the file
+:file:`Misc/SpecialBuilds.txt` in the Python source distribution. Builds are
+available that support tracing of reference counts, debugging the memory
+allocator, or low-level profiling of the main interpreter loop.  Only the most
+frequently-used builds will be described in the remainder of this section.
+
+Compiling the interpreter with the :c:macro:`Py_DEBUG` macro defined produces
+what is generally meant by "a debug build" of Python. :c:macro:`Py_DEBUG` is
+enabled in the Unix build by adding ``--with-pydebug`` to the
+:file:`./configure` command.  It is also implied by the presence of the
+not-Python-specific :c:macro:`_DEBUG` macro.  When :c:macro:`Py_DEBUG` is enabled
+in the Unix build, compiler optimization is disabled.
+
+In addition to the reference count debugging described below, the following
+extra checks are performed:
+
+* Extra checks are added to the object allocator.
+
+* Extra checks are added to the parser and compiler.
+
+* Downcasts from wide types to narrow types are checked for loss of information.
+
+* A number of assertions are added to the dictionary and set implementations.
+  In addition, the set object acquires a :meth:`test_c_api` method.
+
+* Sanity checks of the input arguments are added to frame creation.
+
+* The storage for ints is initialized with a known invalid pattern to catch
+  reference to uninitialized digits.
+
+* Low-level tracing and extra exception checking are added to the runtime
+  virtual machine.
+
+* Extra checks are added to the memory arena implementation.
+
+* Extra debugging is added to the thread module.
+
+There may be additional checks not mentioned here.
+
+Defining :c:macro:`Py_TRACE_REFS` enables reference tracing.  When defined, a
+circular doubly linked list of active objects is maintained by adding two extra
+fields to every :c:type:`PyObject`.  Total allocations are tracked as well.  Upon
+exit, all existing references are printed.  (In interactive mode this happens
+after every statement run by the interpreter.)  Implied by :c:macro:`Py_DEBUG`.
+
+Please refer to :file:`Misc/SpecialBuilds.txt` in the Python source distribution
+for more detailed information.
+

third_party/python/Doc/c-api/iter.rst

@@ -0,0 +1,46 @@
+.. highlightlang:: c
+
+.. _iterator:
+
+Iterator Protocol
+=================
+
+There are two functions specifically for working with iterators.
+
+.. c:function:: int PyIter_Check(PyObject *o)
+
+   Return true if the object *o* supports the iterator protocol.
+
+
+.. c:function:: PyObject* PyIter_Next(PyObject *o)
+
+   Return the next value from the iteration *o*.  The object must be an iterator
+   (it is up to the caller to check this).  If there are no remaining values,
+   returns *NULL* with no exception set.  If an error occurs while retrieving
+   the item, returns *NULL* and passes along the exception.
+
+To write a loop which iterates over an iterator, the C code should look
+something like this::
+
+   PyObject *iterator = PyObject_GetIter(obj);
+   PyObject *item;
+
+   if (iterator == NULL) {
+       /* propagate error */
+   }
+
+   while (item = PyIter_Next(iterator)) {
+       /* do something with item */
+       ...
+       /* release reference when done */
+       Py_DECREF(item);
+   }
+
+   Py_DECREF(iterator);
+
+   if (PyErr_Occurred()) {
+       /* propagate error */
+   }
+   else {
+       /* continue doing useful work */
+   }

third_party/python/Doc/c-api/iterator.rst

@@ -0,0 +1,50 @@
+.. highlightlang:: c
+
+.. _iterator-objects:
+
+Iterator Objects
+----------------
+
+Python provides two general-purpose iterator objects.  The first, a sequence
+iterator, works with an arbitrary sequence supporting the :meth:`__getitem__`
+method.  The second works with a callable object and a sentinel value, calling
+the callable for each item in the sequence, and ending the iteration when the
+sentinel value is returned.
+
+
+.. c:var:: PyTypeObject PySeqIter_Type
+
+   Type object for iterator objects returned by :c:func:`PySeqIter_New` and the
+   one-argument form of the :func:`iter` built-in function for built-in sequence
+   types.
+
+
+.. c:function:: int PySeqIter_Check(op)
+
+   Return true if the type of *op* is :c:data:`PySeqIter_Type`.
+
+
+.. c:function:: PyObject* PySeqIter_New(PyObject *seq)
+
+   Return an iterator that works with a general sequence object, *seq*.  The
+   iteration ends when the sequence raises :exc:`IndexError` for the subscripting
+   operation.
+
+
+.. c:var:: PyTypeObject PyCallIter_Type
+
+   Type object for iterator objects returned by :c:func:`PyCallIter_New` and the
+   two-argument form of the :func:`iter` built-in function.
+
+
+.. c:function:: int PyCallIter_Check(op)
+
+   Return true if the type of *op* is :c:data:`PyCallIter_Type`.
+
+
+.. c:function:: PyObject* PyCallIter_New(PyObject *callable, PyObject *sentinel)
+
+   Return a new iterator.  The first parameter, *callable*, can be any Python
+   callable object that can be called with no parameters; each call to it should
+   return the next item in the iteration.  When *callable* returns a value equal to
+   *sentinel*, the iteration will be terminated.

third_party/python/Doc/c-api/list.rst

@@ -0,0 +1,151 @@
+.. highlightlang:: c
+
+.. _listobjects:
+
+List Objects
+------------
+
+.. index:: object: list
+
+
+.. c:type:: PyListObject
+
+   This subtype of :c:type:`PyObject` represents a Python list object.
+
+
+.. c:var:: PyTypeObject PyList_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python list type.
+   This is the same object as :class:`list` in the Python layer.
+
+
+.. c:function:: int PyList_Check(PyObject *p)
+
+   Return true if *p* is a list object or an instance of a subtype of the list
+   type.
+
+
+.. c:function:: int PyList_CheckExact(PyObject *p)
+
+   Return true if *p* is a list object, but not an instance of a subtype of
+   the list type.
+
+
+.. c:function:: PyObject* PyList_New(Py_ssize_t len)
+
+   Return a new list of length *len* on success, or *NULL* on failure.
+
+   .. note::
+
+      If *len* is greater than zero, the returned list object's items are
+      set to ``NULL``.  Thus you cannot use abstract API functions such as
+      :c:func:`PySequence_SetItem`  or expose the object to Python code before
+      setting all items to a real object with :c:func:`PyList_SetItem`.
+
+
+.. c:function:: Py_ssize_t PyList_Size(PyObject *list)
+
+   .. index:: builtin: len
+
+   Return the length of the list object in *list*; this is equivalent to
+   ``len(list)`` on a list object.
+
+
+.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
+
+   Macro form of :c:func:`PyList_Size` without error checking.
+
+
+.. c:function:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
+
+   Return the object at position *index* in the list pointed to by *list*.  The
+   position must be positive, indexing from the end of the list is not
+   supported.  If *index* is out of bounds, return *NULL* and set an
+   :exc:`IndexError` exception.
+
+
+.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
+
+   Macro form of :c:func:`PyList_GetItem` without error checking.
+
+
+.. c:function:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
+
+   Set the item at index *index* in list to *item*.  Return ``0`` on success
+   or ``-1`` on failure.
+
+   .. note::
+
+      This function "steals" a reference to *item* and discards a reference to
+      an item already in the list at the affected position.
+
+
+.. c:function:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
+
+   Macro form of :c:func:`PyList_SetItem` without error checking. This is
+   normally only used to fill in new lists where there is no previous content.
+
+   .. note::
+
+      This macro "steals" a reference to *item*, and, unlike
+      :c:func:`PyList_SetItem`, does *not* discard a reference to any item that
+      is being replaced; any reference in *list* at position *i* will be
+      leaked.
+
+
+.. c:function:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
+
+   Insert the item *item* into list *list* in front of index *index*.  Return
+   ``0`` if successful; return ``-1`` and set an exception if unsuccessful.
+   Analogous to ``list.insert(index, item)``.
+
+
+.. c:function:: int PyList_Append(PyObject *list, PyObject *item)
+
+   Append the object *item* at the end of list *list*. Return ``0`` if
+   successful; return ``-1`` and set an exception if unsuccessful.  Analogous
+   to ``list.append(item)``.
+
+
+.. c:function:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
+
+   Return a list of the objects in *list* containing the objects *between* *low*
+   and *high*.  Return *NULL* and set an exception if unsuccessful.  Analogous
+   to ``list[low:high]``.  Negative indices, as when slicing from Python, are not
+   supported.
+
+
+.. c:function:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
+
+   Set the slice of *list* between *low* and *high* to the contents of
+   *itemlist*.  Analogous to ``list[low:high] = itemlist``. The *itemlist* may
+   be *NULL*, indicating the assignment of an empty list (slice deletion).
+   Return ``0`` on success, ``-1`` on failure.  Negative indices, as when
+   slicing from Python, are not supported.
+
+
+.. c:function:: int PyList_Sort(PyObject *list)
+
+   Sort the items of *list* in place.  Return ``0`` on success, ``-1`` on
+   failure.  This is equivalent to ``list.sort()``.
+
+
+.. c:function:: int PyList_Reverse(PyObject *list)
+
+   Reverse the items of *list* in place.  Return ``0`` on success, ``-1`` on
+   failure.  This is the equivalent of ``list.reverse()``.
+
+
+.. c:function:: PyObject* PyList_AsTuple(PyObject *list)
+
+   .. index:: builtin: tuple
+
+   Return a new tuple object containing the contents of *list*; equivalent to
+   ``tuple(list)``.
+
+
+.. c:function:: int PyList_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+
+   .. versionadded:: 3.3

third_party/python/Doc/c-api/long.rst

@@ -0,0 +1,295 @@
+.. highlightlang:: c
+
+.. _longobjects:
+
+Integer Objects
+---------------
+
+.. index:: object: long integer
+           object: integer
+
+All integers are implemented as "long" integer objects of arbitrary size.
+
+On error, most ``PyLong_As*`` APIs return ``(return type)-1`` which cannot be
+distinguished from a number.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+.. c:type:: PyLongObject
+
+   This subtype of :c:type:`PyObject` represents a Python integer object.
+
+
+.. c:var:: PyTypeObject PyLong_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python integer type.
+   This is the same object as :class:`int` in the Python layer.
+
+
+.. c:function:: int PyLong_Check(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyLongObject` or a subtype of
+   :c:type:`PyLongObject`.
+
+
+.. c:function:: int PyLong_CheckExact(PyObject *p)
+
+   Return true if its argument is a :c:type:`PyLongObject`, but not a subtype of
+   :c:type:`PyLongObject`.
+
+
+.. c:function:: PyObject* PyLong_FromLong(long v)
+
+   Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure.
+
+   The current implementation keeps an array of integer objects for all integers
+   between ``-5`` and ``256``, when you create an int in that range you actually
+   just get back a reference to the existing object. So it should be possible to
+   change the value of ``1``.  I suspect the behaviour of Python in this case is
+   undefined. :-)
+
+
+.. c:function:: PyObject* PyLong_FromUnsignedLong(unsigned long v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long`, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`Py_ssize_t`, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromSize_t(size_t v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`size_t`, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromLongLong(long long v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`long long`, or *NULL*
+   on failure.
+
+
+.. c:function:: PyObject* PyLong_FromUnsignedLongLong(unsigned long long v)
+
+   Return a new :c:type:`PyLongObject` object from a C :c:type:`unsigned long long`,
+   or *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromDouble(double v)
+
+   Return a new :c:type:`PyLongObject` object from the integer part of *v*, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyLong_FromString(const char *str, char **pend, int base)
+
+   Return a new :c:type:`PyLongObject` based on the string value in *str*, which
+   is interpreted according to the radix in *base*.  If *pend* is non-*NULL*,
+   *\*pend* will point to the first character in *str* which follows the
+   representation of the number.  If *base* is ``0``, *str* is interpreted using
+   the :ref:`integers` definition; in this case, leading zeros in a
+   non-zero decimal number raises a :exc:`ValueError`. If *base* is not ``0``,
+   it must be between ``2`` and ``36``, inclusive.  Leading spaces and single
+   underscores after a base specifier and between digits are ignored.  If there
+   are no digits, :exc:`ValueError` will be raised.
+
+
+.. c:function:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base)
+
+   Convert a sequence of Unicode digits to a Python integer value.  The Unicode
+   string is first encoded to a byte string using :c:func:`PyUnicode_EncodeDecimal`
+   and then converted using :c:func:`PyLong_FromString`.
+
+   .. deprecated-removed:: 3.3 4.0
+      Part of the old-style :c:type:`Py_UNICODE` API; please migrate to using
+      :c:func:`PyLong_FromUnicodeObject`.
+
+
+.. c:function:: PyObject* PyLong_FromUnicodeObject(PyObject *u, int base)
+
+   Convert a sequence of Unicode digits in the string *u* to a Python integer
+   value.  The Unicode string is first encoded to a byte string using
+   :c:func:`PyUnicode_EncodeDecimal` and then converted using
+   :c:func:`PyLong_FromString`.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyLong_FromVoidPtr(void *p)
+
+   Create a Python integer from the pointer *p*. The pointer value can be
+   retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`.
+
+
+.. XXX alias PyLong_AS_LONG (for now)
+.. c:function:: long PyLong_AsLong(PyObject *obj)
+
+   .. index::
+      single: LONG_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
+   (if present) to convert it to a :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
+   :c:type:`long`.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: long PyLong_AsLongAndOverflow(PyObject *obj, int *overflow)
+
+   Return a C :c:type:`long` representation of *obj*.  If *obj* is not an
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
+   (if present) to convert it to a :c:type:`PyLongObject`.
+
+   If the value of *obj* is greater than :const:`LONG_MAX` or less than
+   :const:`LONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively, and
+   return ``-1``; otherwise, set *\*overflow* to ``0``.  If any other exception
+   occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: long long PyLong_AsLongLong(PyObject *obj)
+
+   .. index::
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
+   (if present) to convert it to a :c:type:`PyLongObject`.
+
+   Raise :exc:`OverflowError` if the value of *obj* is out of range for a
+   :c:type:`long`.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: long long PyLong_AsLongLongAndOverflow(PyObject *obj, int *overflow)
+
+   Return a C :c:type:`long long` representation of *obj*.  If *obj* is not an
+   instance of :c:type:`PyLongObject`, first call its :meth:`__int__` method
+   (if present) to convert it to a :c:type:`PyLongObject`.
+
+   If the value of *obj* is greater than :const:`PY_LLONG_MAX` or less than
+   :const:`PY_LLONG_MIN`, set *\*overflow* to ``1`` or ``-1``, respectively,
+   and return ``-1``; otherwise, set *\*overflow* to ``0``.  If any other
+   exception occurs set *\*overflow* to ``0`` and return ``-1`` as usual.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+   .. versionadded:: 3.2
+
+
+.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong)
+
+   .. index::
+      single: PY_SSIZE_T_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`Py_ssize_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
+   :c:type:`Py_ssize_t`.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: unsigned long PyLong_AsUnsignedLong(PyObject *pylong)
+
+   .. index::
+      single: ULONG_MAX
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`unsigned 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 a
+   :c:type:`unsigned long`.
+
+   Returns ``(unsigned long)-1`` on error.
+   Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: size_t PyLong_AsSize_t(PyObject *pylong)
+
+   .. index::
+      single: SIZE_MAX
+      single: OverflowError (built-in exception)
+
+   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
+   :c:type:`size_t`.
+
+   Returns ``(size_t)-1`` on error.
+   Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: unsigned long long PyLong_AsUnsignedLongLong(PyObject *pylong)
+
+   .. index::
+      single: OverflowError (built-in exception)
+
+   Return a C :c:type:`unsigned 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
+   :c:type:`unsigned long long`.
+
+   Returns ``(unsigned long long)-1`` on error.
+   Use :c:func:`PyErr_Occurred` to disambiguate.
+
+   .. versionchanged:: 3.1
+      A negative *pylong* now raises :exc:`OverflowError`, not :exc:`TypeError`.
+
+
+.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *obj)
+
+   Return a C :c:type:`unsigned long` representation of *obj*.  If *obj*
+   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
+   method (if present) to convert it to a :c:type:`PyLongObject`.
+
+   If the value of *obj* is out of range for an :c:type:`unsigned long`,
+   return the reduction of that value modulo ``ULONG_MAX + 1``.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: unsigned long long PyLong_AsUnsignedLongLongMask(PyObject *obj)
+
+   Return a C :c:type:`unsigned long long` representation of *obj*.  If *obj*
+   is not an instance of :c:type:`PyLongObject`, first call its :meth:`__int__`
+   method (if present) to convert it to a :c:type:`PyLongObject`.
+
+   If the value of *obj* is out of range for an :c:type:`unsigned long long`,
+   return the reduction of that value modulo ``PY_ULLONG_MAX + 1``.
+
+   Returns ``-1`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: double PyLong_AsDouble(PyObject *pylong)
+
+   Return a C :c:type:`double` 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
+   :c:type:`double`.
+
+   Returns ``-1.0`` on error.  Use :c:func:`PyErr_Occurred` to disambiguate.
+
+
+.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong)
+
+   Convert a Python integer *pylong* to a C :c:type:`void` pointer.
+   If *pylong* cannot be converted, an :exc:`OverflowError` will be raised.  This
+   is only assured to produce a usable :c:type:`void` pointer for values created
+   with :c:func:`PyLong_FromVoidPtr`.
+
+   Returns *NULL* on error.  Use :c:func:`PyErr_Occurred` to disambiguate.

third_party/python/Doc/c-api/mapping.rst

@@ -0,0 +1,94 @@
+.. highlightlang:: c
+
+.. _mapping:
+
+Mapping Protocol
+================
+
+See also :c:func:`PyObject_GetItem`, :c:func:`PyObject_SetItem` and
+:c:func:`PyObject_DelItem`.
+
+
+.. c:function:: int PyMapping_Check(PyObject *o)
+
+   Return ``1`` if the object provides mapping protocol or supports slicing,
+   and ``0`` otherwise.  Note that it returns ``1`` for Python classes with
+   a :meth:`__getitem__` method since in general case it is impossible to
+   determine what the type of keys it supports.  This function always
+   succeeds.
+
+
+.. c:function:: Py_ssize_t PyMapping_Size(PyObject *o)
+               Py_ssize_t PyMapping_Length(PyObject *o)
+
+   .. index:: builtin: len
+
+   Returns the number of keys in object *o* on success, and ``-1`` on failure.
+   This is equivalent to the Python expression ``len(o)``.
+
+
+.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, const char *key)
+
+   Return element of *o* corresponding to the string *key* or *NULL* on failure.
+   This is the equivalent of the Python expression ``o[key]``.
+   See also :c:func:`PyObject_GetItem`.
+
+
+.. c:function:: int PyMapping_SetItemString(PyObject *o, const char *key, PyObject *v)
+
+   Map the string *key* to the value *v* in object *o*.  Returns ``-1`` on
+   failure.  This is the equivalent of the Python statement ``o[key] = v``.
+   See also :c:func:`PyObject_SetItem`.
+
+
+.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key)
+
+   Remove the mapping for the object *key* from the object *o*.  Return ``-1``
+   on failure.  This is equivalent to the Python statement ``del o[key]``.
+   This is an alias of :c:func:`PyObject_DelItem`.
+
+
+.. c:function:: int PyMapping_DelItemString(PyObject *o, const char *key)
+
+   Remove the mapping for the string *key* from the object *o*.  Return ``-1``
+   on failure.  This is equivalent to the Python statement ``del o[key]``.
+
+
+.. c:function:: int PyMapping_HasKey(PyObject *o, PyObject *key)
+
+   Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
+   This is equivalent to the Python expression ``key in o``.
+   This function always succeeds.
+
+   Note that exceptions which occur while calling the :meth:`__getitem__`
+   method will get suppressed.
+   To get error reporting use :c:func:`PyObject_GetItem()` instead.
+
+
+.. c:function:: int PyMapping_HasKeyString(PyObject *o, const char *key)
+
+   Return ``1`` if the mapping object has the key *key* and ``0`` otherwise.
+   This is equivalent to the Python expression ``key in o``.
+   This function always succeeds.
+
+   Note that exceptions which occur while calling the :meth:`__getitem__`
+   method and creating a temporary string object will get suppressed.
+   To get error reporting use :c:func:`PyMapping_GetItemString()` instead.
+
+
+.. c:function:: PyObject* PyMapping_Keys(PyObject *o)
+
+   On success, return a list or tuple of the keys in object *o*.  On failure,
+   return *NULL*.
+
+
+.. c:function:: PyObject* PyMapping_Values(PyObject *o)
+
+   On success, return a list or tuple of the values in object *o*.  On failure,
+   return *NULL*.
+
+
+.. c:function:: PyObject* PyMapping_Items(PyObject *o)
+
+   On success, return a list or tuple of the items in object *o*, where each item
+   is a tuple containing a key-value pair.  On failure, return *NULL*.

third_party/python/Doc/c-api/marshal.rst

@@ -0,0 +1,94 @@
+.. highlightlang:: c
+
+.. _marshalling-utils:
+
+Data marshalling support
+========================
+
+These routines allow C code to work with serialized objects using the same
+data format as the :mod:`marshal` module.  There are functions to write data
+into the serialization format, and additional functions that can be used to
+read the data back.  Files used to store marshalled data must be opened in
+binary mode.
+
+Numeric values are stored with the least significant byte first.
+
+The module supports two versions of the data format: version 0 is the
+historical version, version 1 shares interned strings in the file, and upon
+unmarshalling.  Version 2 uses a binary format for floating point numbers.
+*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
+
+
+.. c:function:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
+
+   Marshal a :c:type:`long` integer, *value*, to *file*.  This will only write
+   the least-significant 32 bits of *value*; regardless of the size of the
+   native :c:type:`long` type.  *version* indicates the file format.
+
+
+.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
+
+   Marshal a Python object, *value*, to *file*.
+   *version* indicates the file format.
+
+
+.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version)
+
+   Return a bytes object containing the marshalled representation of *value*.
+   *version* indicates the file format.
+
+
+The following functions allow marshalled values to be read back in.
+
+
+.. c:function:: long PyMarshal_ReadLongFromFile(FILE *file)
+
+   Return a C :c:type:`long` from the data stream in a :c:type:`FILE\*` opened
+   for reading.  Only a 32-bit value can be read in using this function,
+   regardless of the native size of :c:type:`long`.
+
+   On error, sets the appropriate exception (:exc:`EOFError`) and returns
+   ``-1``.
+
+
+.. c:function:: int PyMarshal_ReadShortFromFile(FILE *file)
+
+   Return a C :c:type:`short` from the data stream in a :c:type:`FILE\*` opened
+   for reading.  Only a 16-bit value can be read in using this function,
+   regardless of the native size of :c:type:`short`.
+
+   On error, sets the appropriate exception (:exc:`EOFError`) and returns
+   ``-1``.
+
+
+.. c:function:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
+
+   Return a Python object from the data stream in a :c:type:`FILE\*` opened for
+   reading.
+
+   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
+   or :exc:`TypeError`) and returns *NULL*.
+
+
+.. c:function:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
+
+   Return a Python object from the data stream in a :c:type:`FILE\*` opened for
+   reading.  Unlike :c:func:`PyMarshal_ReadObjectFromFile`, this function
+   assumes that no further objects will be read from the file, allowing it to
+   aggressively load file data into memory so that the de-serialization can
+   operate from data in memory rather than reading a byte at a time from the
+   file.  Only use these variant if you are certain that you won't be reading
+   anything else from the file.
+
+   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
+   or :exc:`TypeError`) and returns *NULL*.
+
+
+.. c:function:: PyObject* PyMarshal_ReadObjectFromString(const char *data, Py_ssize_t len)
+
+   Return a Python object from the data stream in a byte buffer
+   containing *len* bytes pointed to by *data*.
+
+   On error, sets the appropriate exception (:exc:`EOFError`, :exc:`ValueError`
+   or :exc:`TypeError`) and returns *NULL*.
+

third_party/python/Doc/c-api/memory.rst

@@ -0,0 +1,546 @@
+.. highlightlang:: c
+
+
+.. _memory:
+
+*****************
+Memory Management
+*****************
+
+.. sectionauthor:: Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>
+
+
+
+.. _memoryoverview:
+
+Overview
+========
+
+Memory management in Python involves a private heap containing all Python
+objects and data structures. The management of this private heap is ensured
+internally by the *Python memory manager*.  The Python memory manager has
+different components which deal with various dynamic storage management aspects,
+like sharing, segmentation, preallocation or caching.
+
+At the lowest level, a raw memory allocator ensures that there is enough room in
+the private heap for storing all Python-related data by interacting with the
+memory manager of the operating system. On top of the raw memory allocator,
+several object-specific allocators operate on the same heap and implement
+distinct memory management policies adapted to the peculiarities of every object
+type. For example, integer objects are managed differently within the heap than
+strings, tuples or dictionaries because integers imply different storage
+requirements and speed/space tradeoffs. The Python memory manager thus delegates
+some of the work to the object-specific allocators, but ensures that the latter
+operate within the bounds of the private heap.
+
+It is important to understand that the management of the Python heap is
+performed by the interpreter itself and that the user has no control over it,
+even if they regularly manipulate object pointers to memory blocks inside that
+heap.  The allocation of heap space for Python objects and other internal
+buffers is performed on demand by the Python memory manager through the Python/C
+API functions listed in this document.
+
+.. index::
+   single: malloc()
+   single: calloc()
+   single: realloc()
+   single: free()
+
+To avoid memory corruption, extension writers should never try to operate on
+Python objects with the functions exported by the C library: :c:func:`malloc`,
+:c:func:`calloc`, :c:func:`realloc` and :c:func:`free`.  This will result in  mixed
+calls between the C allocator and the Python memory manager with fatal
+consequences, because they implement different algorithms and operate on
+different heaps.  However, one may safely allocate and release memory blocks
+with the C library allocator for individual purposes, as shown in the following
+example::
+
+   PyObject *res;
+   char *buf = (char *) malloc(BUFSIZ); /* for I/O */
+
+   if (buf == NULL)
+       return PyErr_NoMemory();
+   ...Do some I/O operation involving buf...
+   res = PyBytes_FromString(buf);
+   free(buf); /* malloc'ed */
+   return res;
+
+In this example, the memory request for the I/O buffer is handled by the C
+library allocator. The Python memory manager is involved only in the allocation
+of the string object returned as a result.
+
+In most situations, however, it is recommended to allocate memory from the
+Python heap specifically because the latter is under control of the Python
+memory manager. For example, this is required when the interpreter is extended
+with new object types written in C. Another reason for using the Python heap is
+the desire to *inform* the Python memory manager about the memory needs of the
+extension module. Even when the requested memory is used exclusively for
+internal, highly-specific purposes, delegating all memory requests to the Python
+memory manager causes the interpreter to have a more accurate image of its
+memory footprint as a whole. Consequently, under certain circumstances, the
+Python memory manager may or may not trigger appropriate actions, like garbage
+collection, memory compaction or other preventive procedures. Note that by using
+the C library allocator as shown in the previous example, the allocated memory
+for the I/O buffer escapes completely the Python memory manager.
+
+.. seealso::
+
+   The :envvar:`PYTHONMALLOC` environment variable can be used to configure
+   the memory allocators used by Python.
+
+   The :envvar:`PYTHONMALLOCSTATS` environment variable can be used to print
+   statistics of the :ref:`pymalloc memory allocator <pymalloc>` every time a
+   new pymalloc object arena is created, and on shutdown.
+
+
+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:`calloc`, :c:func:`realloc` and :c:func:`free`; call
+``malloc(1)`` (or ``calloc(1, 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_RawCalloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a distinct
+   non-*NULL* pointer if possible, as if ``PyMem_RawCalloc(1, 1)`` had been
+   called instead.
+
+   .. versionadded:: 3.5
+
+
+.. 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`, :c:func:`PyMem_RawRealloc` or
+   :c:func:`PyMem_RawCalloc`.
+
+   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`, :c:func:`PyMem_RawRealloc` or
+   :c:func:`PyMem_RawCalloc`.  Otherwise, or if ``PyMem_RawFree(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.
+
+By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`.
+
+.. warning::
+
+   The :term:`GIL <global interpreter lock>` must be held when using these
+   functions.
+
+.. versionchanged:: 3.6
+
+   The default allocator is now pymalloc instead of system :c:func:`malloc`.
+
+.. c:function:: void* PyMem_Malloc(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_Malloc(1)`` had been called instead. The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: void* PyMem_Calloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a distinct
+   non-*NULL* pointer if possible, as if ``PyMem_Calloc(1, 1)`` had been called
+   instead.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: void* PyMem_Realloc(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_Malloc(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_Malloc`, :c:func:`PyMem_Realloc` or :c:func:`PyMem_Calloc`.
+
+   If the request fails, :c:func:`PyMem_Realloc` returns *NULL* and *p* remains
+   a valid pointer to the previous memory area.
+
+
+.. c:function:: void PyMem_Free(void *p)
+
+   Frees the memory block pointed to by *p*, which must have been returned by a
+   previous call to :c:func:`PyMem_Malloc`, :c:func:`PyMem_Realloc` or
+   :c:func:`PyMem_Calloc`.  Otherwise, or if ``PyMem_Free(p)`` has been called
+   before, undefined behavior occurs.
+
+   If *p* is *NULL*, no operation is performed.
+
+The following type-oriented macros are provided for convenience.  Note  that
+*TYPE* refers to any C type.
+
+
+.. c:function:: TYPE* PyMem_New(TYPE, size_t n)
+
+   Same as :c:func:`PyMem_Malloc`, but allocates ``(n * sizeof(TYPE))`` bytes of
+   memory.  Returns a pointer cast to :c:type:`TYPE\*`.  The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: TYPE* PyMem_Resize(void *p, TYPE, size_t n)
+
+   Same as :c:func:`PyMem_Realloc`, but the memory block is resized to ``(n *
+   sizeof(TYPE))`` bytes.  Returns a pointer cast to :c:type:`TYPE\*`. On return,
+   *p* will be a pointer to the new memory area, or *NULL* in the event of
+   failure.
+
+   This is a C preprocessor macro; *p* is always reassigned.  Save the original
+   value of *p* to avoid losing memory when handling errors.
+
+
+.. c:function:: void PyMem_Del(void *p)
+
+   Same as :c:func:`PyMem_Free`.
+
+In addition, the following macro sets are provided for calling the Python memory
+allocator directly, without involving the C API functions listed above. However,
+note that their use does not preserve binary compatibility across Python
+versions and is therefore deprecated in extension modules.
+
+* ``PyMem_MALLOC(size)``
+* ``PyMem_NEW(type, size)``
+* ``PyMem_REALLOC(ptr, size)``
+* ``PyMem_RESIZE(ptr, type, size)``
+* ``PyMem_FREE(ptr)``
+* ``PyMem_DEL(ptr)``
+
+
+Object allocators
+=================
+
+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.
+
+By default, these functions use :ref:`pymalloc memory allocator <pymalloc>`.
+
+.. warning::
+
+   The :term:`GIL <global interpreter lock>` must be held when using these
+   functions.
+
+.. c:function:: void* PyObject_Malloc(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 ``PyObject_Malloc(1)`` had been called instead. The memory will not have
+   been initialized in any way.
+
+
+.. c:function:: void* PyObject_Calloc(size_t nelem, size_t elsize)
+
+   Allocates *nelem* elements each whose size in bytes is *elsize* and returns
+   a pointer of type :c:type:`void\*` to the allocated memory, or *NULL* if the
+   request fails. The memory is initialized to zeros.
+
+   Requesting zero elements or elements of size zero bytes returns a distinct
+   non-*NULL* pointer if possible, as if ``PyObject_Calloc(1, 1)`` had been called
+   instead.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: void* PyObject_Realloc(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 ``PyObject_Malloc(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:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or :c:func:`PyObject_Calloc`.
+
+   If the request fails, :c:func:`PyObject_Realloc` returns *NULL* and *p* remains
+   a valid pointer to the previous memory area.
+
+
+.. c:function:: void PyObject_Free(void *p)
+
+   Frees the memory block pointed to by *p*, which must have been returned by a
+   previous call to :c:func:`PyObject_Malloc`, :c:func:`PyObject_Realloc` or
+   :c:func:`PyObject_Calloc`.  Otherwise, or if ``PyObject_Free(p)`` has been called
+   before, undefined behavior occurs.
+
+   If *p* is *NULL*, no operation is performed.
+
+
+Customize Memory Allocators
+===========================
+
+.. versionadded:: 3.4
+
+.. c:type:: PyMemAllocatorEx
+
+   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* calloc(void *ctx, size_t nelem, size_t elsize)`` | allocate a memory block initialized   |
+   |                                                          | with zeros                            |
+   +----------------------------------------------------------+---------------------------------------+
+   | ``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                   |
+   +----------------------------------------------------------+---------------------------------------+
+
+   .. versionchanged:: 3.5
+      The :c:type:`PyMemAllocator` structure was renamed to
+      :c:type:`PyMemAllocatorEx` and a new ``calloc`` field was added.
+
+
+.. c:type:: PyMemAllocatorDomain
+
+   Enum used to identify an allocator domain. Domains:
+
+   .. c:var:: PYMEM_DOMAIN_RAW
+
+      Functions:
+
+      * :c:func:`PyMem_RawMalloc`
+      * :c:func:`PyMem_RawRealloc`
+      * :c:func:`PyMem_RawCalloc`
+      * :c:func:`PyMem_RawFree`
+
+   .. c:var:: PYMEM_DOMAIN_MEM
+
+      Functions:
+
+      * :c:func:`PyMem_Malloc`,
+      * :c:func:`PyMem_Realloc`
+      * :c:func:`PyMem_Calloc`
+      * :c:func:`PyMem_Free`
+
+   .. c:var:: PYMEM_DOMAIN_OBJ
+
+      Functions:
+
+      * :c:func:`PyObject_Malloc`
+      * :c:func:`PyObject_Realloc`
+      * :c:func:`PyObject_Calloc`
+      * :c:func:`PyObject_Free`
+
+.. c:function:: void PyMem_GetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *allocator)
+
+   Get the memory block allocator of the specified domain.
+
+
+.. c:function:: void PyMem_SetAllocator(PyMemAllocatorDomain domain, PyMemAllocatorEx *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 Python memory allocator functions.
+
+   Newly allocated memory is filled with the byte ``0xCB``, freed memory is
+   filled with the byte ``0xDB``.
+
+   Runtime 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)
+   - Check that the :term:`GIL <global interpreter lock>` is held when
+     allocator functions of :c:data:`PYMEM_DOMAIN_OBJ` (ex:
+     :c:func:`PyObject_Malloc`) and :c:data:`PYMEM_DOMAIN_MEM` (ex:
+     :c:func:`PyMem_Malloc`) domains are called
+
+   On error, the debug hooks use the :mod:`tracemalloc` module to get the
+   traceback where a memory block was allocated. The traceback is only
+   displayed if :mod:`tracemalloc` is tracing Python memory allocations and the
+   memory block was traced.
+
+   These hooks are installed by default if Python is compiled in debug
+   mode. The :envvar:`PYTHONMALLOC` environment variable can be used to install
+   debug hooks on a Python compiled in release mode.
+
+   .. versionchanged:: 3.6
+      This function now also works on Python compiled in release mode.
+      On error, the debug hooks now use :mod:`tracemalloc` to get the traceback
+      where a memory block was allocated. The debug hooks now also check
+      if the GIL is held when functions of :c:data:`PYMEM_DOMAIN_OBJ` and
+      :c:data:`PYMEM_DOMAIN_MEM` domains are called.
+
+
+.. _pymalloc:
+
+The pymalloc allocator
+======================
+
+Python has a *pymalloc* allocator optimized for small objects (smaller or equal
+to 512 bytes) with a short lifetime. It uses memory mappings called "arenas"
+with a fixed size of 256 KB. It falls back to :c:func:`PyMem_RawMalloc` and
+:c:func:`PyMem_RawRealloc` for allocations larger than 512 bytes.
+
+*pymalloc* is the default allocator of the :c:data:`PYMEM_DOMAIN_MEM` (ex:
+:c:func:`PyMem_Malloc`) and :c:data:`PYMEM_DOMAIN_OBJ` (ex:
+:c:func:`PyObject_Malloc`) domains.
+
+The 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.
+
+Customize pymalloc Arena Allocator
+----------------------------------
+
+.. 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
+========
+
+Here is the example from section :ref:`memoryoverview`, rewritten so that the
+I/O buffer is allocated from the Python heap by using the first function set::
+
+   PyObject *res;
+   char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */
+
+   if (buf == NULL)
+       return PyErr_NoMemory();
+   /* ...Do some I/O operation involving buf... */
+   res = PyBytes_FromString(buf);
+   PyMem_Free(buf); /* allocated with PyMem_Malloc */
+   return res;
+
+The same code using the type-oriented function set::
+
+   PyObject *res;
+   char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
+
+   if (buf == NULL)
+       return PyErr_NoMemory();
+   /* ...Do some I/O operation involving buf... */
+   res = PyBytes_FromString(buf);
+   PyMem_Del(buf); /* allocated with PyMem_New */
+   return res;
+
+Note that in the two examples above, the buffer is always manipulated via
+functions belonging to the same set. Indeed, it is required to use the same
+memory API family for a given memory block, so that the risk of mixing different
+allocators is reduced to a minimum. The following code sequence contains two
+errors, one of which is labeled as *fatal* because it mixes two different
+allocators operating on different heaps. ::
+
+   char *buf1 = PyMem_New(char, BUFSIZ);
+   char *buf2 = (char *) malloc(BUFSIZ);
+   char *buf3 = (char *) PyMem_Malloc(BUFSIZ);
+   ...
+   PyMem_Del(buf3);  /* Wrong -- should be PyMem_Free() */
+   free(buf2);       /* Right -- allocated via malloc() */
+   free(buf1);       /* Fatal -- should be PyMem_Del()  */
+
+In addition to the functions aimed at handling raw memory blocks from the Python
+heap, objects in Python are allocated and released with :c:func:`PyObject_New`,
+:c:func:`PyObject_NewVar` and :c:func:`PyObject_Del`.
+
+These will be explained in the next chapter on defining and implementing new
+object types in C.
+

third_party/python/Doc/c-api/memoryview.rst

@@ -0,0 +1,63 @@
+.. highlightlang:: c
+
+.. _memoryview-objects:
+
+.. index::
+   object: memoryview
+
+MemoryView objects
+------------------
+
+A :class:`memoryview` object exposes the C level :ref:`buffer interface
+<bufferobjects>` as a Python object which can then be passed around like
+any other object.
+
+
+.. c:function:: PyObject *PyMemoryView_FromObject(PyObject *obj)
+
+   Create a memoryview object from an object that provides the buffer interface.
+   If *obj* supports writable buffer exports, the memoryview object will be
+   read/write, otherwise it may be either read-only or read/write at the
+   discretion of the exporter.
+
+.. c:function:: PyObject *PyMemoryView_FromMemory(char *mem, Py_ssize_t size, int flags)
+
+   Create a memoryview object using *mem* as the underlying buffer.
+   *flags* can be one of :c:macro:`PyBUF_READ` or :c:macro:`PyBUF_WRITE`.
+
+   .. versionadded:: 3.3
+
+.. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view)
+
+   Create a memoryview object wrapping the given buffer structure *view*.
+   For simple byte buffers, :c:func:`PyMemoryView_FromMemory` is the preferred
+   function.
+
+.. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order)
+
+   Create a memoryview object to a :term:`contiguous` chunk of memory (in either
+   'C' or 'F'ortran *order*) from an object that defines the buffer
+   interface. If memory is contiguous, the memoryview object points to the
+   original memory. Otherwise, a copy is made and the memoryview points to a
+   new bytes object.
+
+
+.. c:function:: int PyMemoryView_Check(PyObject *obj)
+
+   Return true if the object *obj* is a memoryview object.  It is not
+   currently allowed to create subclasses of :class:`memoryview`.
+
+
+.. c:function:: Py_buffer *PyMemoryView_GET_BUFFER(PyObject *mview)
+
+   Return a pointer to the memoryview's private copy of the exporter's buffer.
+   *mview* **must** be a memoryview instance; this macro doesn't check its type,
+   you must do it yourself or you will risk crashes.
+
+.. c:function:: Py_buffer *PyMemoryView_GET_BASE(PyObject *mview)
+
+   Return either a pointer to the exporting object that the memoryview is based
+   on or *NULL* if the memoryview has been created by one of the functions
+   :c:func:`PyMemoryView_FromMemory` or :c:func:`PyMemoryView_FromBuffer`.
+   *mview* **must** be a memoryview instance.
+

third_party/python/Doc/c-api/method.rst

@@ -0,0 +1,100 @@
+.. highlightlang:: c
+
+.. _instancemethod-objects:
+
+Instance Method Objects
+-----------------------
+
+.. index:: object: instancemethod
+
+An instance method is a wrapper for a :c:data:`PyCFunction` and the new way
+to bind a :c:data:`PyCFunction` to a class object. It replaces the former call
+``PyMethod_New(func, NULL, class)``.
+
+
+.. c:var:: PyTypeObject PyInstanceMethod_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python instance
+   method type. It is not exposed to Python programs.
+
+
+.. c:function:: int PyInstanceMethod_Check(PyObject *o)
+
+   Return true if *o* is an instance method object (has type
+   :c:data:`PyInstanceMethod_Type`).  The parameter must not be *NULL*.
+
+
+.. c:function:: PyObject* PyInstanceMethod_New(PyObject *func)
+
+   Return a new instance method object, with *func* being any callable object
+   *func* is the function that will be called when the instance method is
+   called.
+
+
+.. c:function:: PyObject* PyInstanceMethod_Function(PyObject *im)
+
+   Return the function object associated with the instance method *im*.
+
+
+.. c:function:: PyObject* PyInstanceMethod_GET_FUNCTION(PyObject *im)
+
+   Macro version of :c:func:`PyInstanceMethod_Function` which avoids error checking.
+
+
+.. _method-objects:
+
+Method Objects
+--------------
+
+.. index:: object: method
+
+Methods are bound function objects. Methods are always bound to an instance of
+a user-defined class. Unbound methods (methods bound to a class object) are
+no longer available.
+
+
+.. c:var:: PyTypeObject PyMethod_Type
+
+   .. index:: single: MethodType (in module types)
+
+   This instance of :c:type:`PyTypeObject` represents the Python method type.  This
+   is exposed to Python programs as ``types.MethodType``.
+
+
+.. c:function:: int PyMethod_Check(PyObject *o)
+
+   Return true if *o* is a method object (has type :c:data:`PyMethod_Type`).  The
+   parameter must not be *NULL*.
+
+
+.. c:function:: PyObject* PyMethod_New(PyObject *func, PyObject *self)
+
+   Return a new method object, with *func* being any callable object and *self*
+   the instance the method should be bound. *func* is the function that will
+   be called when the method is called. *self* must not be *NULL*.
+
+
+.. c:function:: PyObject* PyMethod_Function(PyObject *meth)
+
+   Return the function object associated with the method *meth*.
+
+
+.. c:function:: PyObject* PyMethod_GET_FUNCTION(PyObject *meth)
+
+   Macro version of :c:func:`PyMethod_Function` which avoids error checking.
+
+
+.. c:function:: PyObject* PyMethod_Self(PyObject *meth)
+
+   Return the instance associated with the method *meth*.
+
+
+.. c:function:: PyObject* PyMethod_GET_SELF(PyObject *meth)
+
+   Macro version of :c:func:`PyMethod_Self` which avoids error checking.
+
+
+.. c:function:: int PyMethod_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+

third_party/python/Doc/c-api/module.rst

@@ -0,0 +1,479 @@
+.. highlightlang:: c
+
+.. _moduleobjects:
+
+Module Objects
+--------------
+
+.. index:: object: module
+
+
+.. c:var:: PyTypeObject PyModule_Type
+
+   .. index:: single: ModuleType (in module types)
+
+   This instance of :c:type:`PyTypeObject` represents the Python module type.  This
+   is exposed to Python programs as ``types.ModuleType``.
+
+
+.. c:function:: int PyModule_Check(PyObject *p)
+
+   Return true if *p* is a module object, or a subtype of a module object.
+
+
+.. c:function:: int PyModule_CheckExact(PyObject *p)
+
+   Return true if *p* is a module object, but not a subtype of
+   :c:data:`PyModule_Type`.
+
+
+.. c:function:: PyObject* PyModule_NewObject(PyObject *name)
+
+   .. index::
+      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*.
+   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)
+
+   Similar to :c:func:`PyModule_NewObject`, but the name is a UTF-8 encoded
+   string instead of a Unicode object.
+
+
+.. c:function:: PyObject* PyModule_GetDict(PyObject *module)
+
+   .. index:: single: __dict__ (module attribute)
+
+   Return the dictionary object that implements *module*'s namespace; this object
+   is the same as the :attr:`~object.__dict__` attribute of the module object.
+   If *module* is not a module object (or a subtype of a module object),
+   :exc:`SystemError` is raised and *NULL* is returned.
+
+   It is recommended extensions use other :c:func:`PyModule_\*` and
+   :c:func:`PyObject_\*` functions rather than directly manipulate a module's
+   :attr:`~object.__dict__`.
+
+
+.. c:function:: PyObject* PyModule_GetNameObject(PyObject *module)
+
+   .. index::
+      single: __name__ (module attribute)
+      single: SystemError (built-in exception)
+
+   Return *module*'s :attr:`__name__` value.  If the module does not provide one,
+   or if it is not a string, :exc:`SystemError` is raised and *NULL* is returned.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: char* PyModule_GetName(PyObject *module)
+
+   Similar to :c:func:`PyModule_GetNameObject` but return the name encoded to
+   ``'utf-8'``.
+
+.. c:function:: void* PyModule_GetState(PyObject *module)
+
+   Return the "state" of the module, that is, a pointer to the block of memory
+   allocated at module creation time, or *NULL*.  See
+   :c:member:`PyModuleDef.m_size`.
+
+
+.. c:function:: PyModuleDef* PyModule_GetDef(PyObject *module)
+
+   Return a pointer to the :c:type:`PyModuleDef` struct from which the module was
+   created, or *NULL* if the module wasn't created from a definition.
+
+
+.. c:function:: PyObject* PyModule_GetFilenameObject(PyObject *module)
+
+   .. index::
+      single: __file__ (module attribute)
+      single: SystemError (built-in exception)
+
+   Return the name of the file from which *module* was loaded using *module*'s
+   :attr:`__file__` attribute.  If this is not defined, or if it is not a
+   unicode string, raise :exc:`SystemError` and return *NULL*; otherwise return
+   a reference to a Unicode object.
+
+   .. versionadded:: 3.2
+
+
+.. c:function:: char* PyModule_GetFilename(PyObject *module)
+
+   Similar to :c:func:`PyModule_GetFilenameObject` but return the filename
+   encoded to 'utf-8'.
+
+   .. deprecated:: 3.2
+      :c:func:`PyModule_GetFilename` raises :c:type:`UnicodeEncodeError` on
+      unencodable filenames, use :c:func:`PyModule_GetFilenameObject` instead.
+
+
+.. _initializing-modules:
+
+Initializing C modules
+^^^^^^^^^^^^^^^^^^^^^^
+
+Modules objects are usually created from extension modules (shared libraries
+which export an initialization function), or compiled-in modules
+(where the initialization function is added using :c:func:`PyImport_AppendInittab`).
+See :ref:`building` or :ref:`extending-with-embedding` for details.
+
+The initialization function can either pass a module definition instance
+to :c:func:`PyModule_Create`, and return the resulting module object,
+or request "multi-phase initialization" by returning the definition struct itself.
+
+.. c:type:: PyModuleDef
+
+   The module definition struct, which holds all information needed to create
+   a module object. There is usually only one statically initialized variable
+   of this type for each module.
+
+   .. c:member:: PyModuleDef_Base m_base
+
+      Always initialize this member to :const:`PyModuleDef_HEAD_INIT`.
+
+   .. c:member:: char* m_name
+
+      Name for the new module.
+
+   .. c:member:: char* m_doc
+
+      Docstring for the module; usually a docstring variable created with
+      :c:func:`PyDoc_STRVAR` is used.
+
+   .. c:member:: Py_ssize_t m_size
+
+      Module state may be kept in a per-module memory area that can be
+      retrieved with :c:func:`PyModule_GetState`, rather than in static globals.
+      This makes modules safe for use in multiple sub-interpreters.
+
+      This memory area is allocated based on *m_size* on module creation,
+      and freed when the module object is deallocated, after the
+      :c:member:`m_free` function has been called, if present.
+
+      Setting ``m_size`` to ``-1`` means that the module does not support
+      sub-interpreters, because it has global state.
+
+      Setting it to a non-negative value means that the module can be
+      re-initialized and specifies the additional amount of memory it requires
+      for its state. Non-negative ``m_size`` is required for multi-phase
+      initialization.
+
+      See :PEP:`3121` for more details.
+
+   .. c:member:: PyMethodDef* m_methods
+
+      A pointer to a table of module-level functions, described by
+      :c:type:`PyMethodDef` values.  Can be *NULL* if no functions are present.
+
+   .. c:member:: PyModuleDef_Slot* m_slots
+
+      An array of slot definitions for multi-phase initialization, terminated by
+      a ``{0, NULL}`` entry.
+      When using single-phase initialization, *m_slots* must be *NULL*.
+
+      .. versionchanged:: 3.5
+
+         Prior to version 3.5, this member was always set to *NULL*,
+         and was defined as:
+
+           .. c:member:: inquiry m_reload
+
+   .. c:member:: traverseproc m_traverse
+
+      A traversal function to call during GC traversal of the module object, or
+      *NULL* if not needed. This function may be called before module state
+      is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
+      and before the :c:member:`Py_mod_exec` function is executed.
+
+   .. c:member:: inquiry m_clear
+
+      A clear function to call during GC clearing of the module object, or
+      *NULL* if not needed. This function may be called before module state
+      is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
+      and before the :c:member:`Py_mod_exec` function is executed.
+
+   .. c:member:: freefunc m_free
+
+      A function to call during deallocation of the module object, or *NULL* if
+      not needed. This function may be called before module state
+      is allocated (:c:func:`PyModule_GetState()` may return `NULL`),
+      and before the :c:member:`Py_mod_exec` function is executed.
+
+Single-phase initialization
+...........................
+
+The module initialization function may create and return the module object
+directly. This is referred to as "single-phase initialization", and uses one
+of the following two module creation functions:
+
+.. c:function:: PyObject* PyModule_Create(PyModuleDef *def)
+
+   Create a new module object, given the definition in *def*.  This behaves
+   like :c:func:`PyModule_Create2` with *module_api_version* set to
+   :const:`PYTHON_API_VERSION`.
+
+
+.. c:function:: PyObject* PyModule_Create2(PyModuleDef *def, int module_api_version)
+
+   Create a new module object, given the definition in *def*, assuming the
+   API version *module_api_version*.  If that version does not match the version
+   of the running interpreter, a :exc:`RuntimeWarning` is emitted.
+
+   .. note::
+
+      Most uses of this function should be using :c:func:`PyModule_Create`
+      instead; only use this if you are sure you need it.
+
+Before it is returned from in the initialization function, the resulting module
+object is typically populated using functions like :c:func:`PyModule_AddObject`.
+
+.. _multi-phase-initialization:
+
+Multi-phase initialization
+..........................
+
+An alternate way to specify extensions is to request "multi-phase initialization".
+Extension modules created this way behave more like Python modules: the
+initialization is split between the *creation phase*, when the module object
+is created, and the *execution phase*, when it is populated.
+The distinction is similar to the :py:meth:`__new__` and :py:meth:`__init__` methods
+of classes.
+
+Unlike modules created using single-phase initialization, these modules are not
+singletons: if the *sys.modules* entry is removed and the module is re-imported,
+a new module object is created, and the old module is subject to normal garbage
+collection -- as with Python modules.
+By default, multiple modules created from the same definition should be
+independent: changes to one should not affect the others.
+This means that all state should be specific to the module object (using e.g.
+using :c:func:`PyModule_GetState`), or its contents (such as the module's
+:attr:`__dict__` or individual classes created with :c:func:`PyType_FromSpec`).
+
+All modules created using multi-phase initialization are expected to support
+:ref:`sub-interpreters <sub-interpreter-support>`. Making sure multiple modules
+are independent is typically enough to achieve this.
+
+To request multi-phase initialization, the initialization function
+(PyInit_modulename) returns a :c:type:`PyModuleDef` instance with non-empty
+:c:member:`~PyModuleDef.m_slots`. Before it is returned, the ``PyModuleDef``
+instance must be initialized with the following function:
+
+.. c:function:: PyObject* PyModuleDef_Init(PyModuleDef *def)
+
+   Ensures a module definition is a properly initialized Python object that
+   correctly reports its type and reference count.
+
+   Returns *def* cast to ``PyObject*``, or *NULL* if an error occurred.
+
+   .. versionadded:: 3.5
+
+The *m_slots* member of the module definition must point to an array of
+``PyModuleDef_Slot`` structures:
+
+.. c:type:: PyModuleDef_Slot
+
+   .. c:member:: int slot
+
+      A slot ID, chosen from the available values explained below.
+
+   .. c:member:: void* value
+
+      Value of the slot, whose meaning depends on the slot ID.
+
+   .. versionadded:: 3.5
+
+The *m_slots* array must be terminated by a slot with id 0.
+
+The available slot types are:
+
+.. c:var:: Py_mod_create
+
+   Specifies a function that is called to create the module object itself.
+   The *value* pointer of this slot must point to a function of the signature:
+
+   .. c:function:: PyObject* create_module(PyObject *spec, PyModuleDef *def)
+
+   The function receives a :py:class:`~importlib.machinery.ModuleSpec`
+   instance, as defined in :PEP:`451`, and the module definition.
+   It should return a new module object, or set an error
+   and return *NULL*.
+
+   This function should be kept minimal. In particular, it should not
+   call arbitrary Python code, as trying to import the same module again may
+   result in an infinite loop.
+
+   Multiple ``Py_mod_create`` slots may not be specified in one module
+   definition.
+
+   If ``Py_mod_create`` is not specified, the import machinery will create
+   a normal module object using :c:func:`PyModule_New`. The name is taken from
+   *spec*, not the definition, to allow extension modules to dynamically adjust
+   to their place in the module hierarchy and be imported under different
+   names through symlinks, all while sharing a single module definition.
+
+   There is no requirement for the returned object to be an instance of
+   :c:type:`PyModule_Type`. Any type can be used, as long as it supports
+   setting and getting import-related attributes.
+   However, only ``PyModule_Type`` instances may be returned if the
+   ``PyModuleDef`` has non-*NULL* ``m_traverse``, ``m_clear``,
+   ``m_free``; non-zero ``m_size``; or slots other than ``Py_mod_create``.
+
+.. c:var:: Py_mod_exec
+
+   Specifies a function that is called to *execute* the module.
+   This is equivalent to executing the code of a Python module: typically,
+   this function adds classes and constants to the module.
+   The signature of the function is:
+
+   .. c:function:: int exec_module(PyObject* module)
+
+   If multiple ``Py_mod_exec`` slots are specified, they are processed in the
+   order they appear in the *m_slots* array.
+
+See :PEP:`489` for more details on multi-phase initialization.
+
+Low-level module creation functions
+...................................
+
+The following functions are called under the hood when using multi-phase
+initialization. They can be used directly, for example when creating module
+objects dynamically. Note that both ``PyModule_FromDefAndSpec`` and
+``PyModule_ExecDef`` must be called to fully initialize a module.
+
+.. c:function:: PyObject * PyModule_FromDefAndSpec(PyModuleDef *def, PyObject *spec)
+
+   Create a new module object, given the definition in *module* and the
+   ModuleSpec *spec*.  This behaves like :c:func:`PyModule_FromDefAndSpec2`
+   with *module_api_version* set to :const:`PYTHON_API_VERSION`.
+
+   .. versionadded:: 3.5
+
+.. c:function:: PyObject * PyModule_FromDefAndSpec2(PyModuleDef *def, PyObject *spec, int module_api_version)
+
+   Create a new module object, given the definition in *module* and the
+   ModuleSpec *spec*, assuming the API version *module_api_version*.
+   If that version does not match the version of the running interpreter,
+   a :exc:`RuntimeWarning` is emitted.
+
+   .. note::
+
+      Most uses of this function should be using :c:func:`PyModule_FromDefAndSpec`
+      instead; only use this if you are sure you need it.
+
+   .. versionadded:: 3.5
+
+.. c:function:: int PyModule_ExecDef(PyObject *module, PyModuleDef *def)
+
+   Process any execution slots (:c:data:`Py_mod_exec`) given in *def*.
+
+   .. versionadded:: 3.5
+
+.. c:function:: int PyModule_SetDocString(PyObject *module, const char *docstring)
+
+   Set the docstring for *module* to *docstring*.
+   This function is called automatically when creating a module from
+   ``PyModuleDef``, using either ``PyModule_Create`` or
+   ``PyModule_FromDefAndSpec``.
+
+   .. versionadded:: 3.5
+
+.. c:function:: int PyModule_AddFunctions(PyObject *module, PyMethodDef *functions)
+
+   Add the functions from the *NULL* terminated *functions* array to *module*.
+   Refer to the :c:type:`PyMethodDef` documentation for details on individual
+   entries (due to the lack of a shared module namespace, module level
+   "functions" implemented in C typically receive the module as their first
+   parameter, making them similar to instance methods on Python classes).
+   This function is called automatically when creating a module from
+   ``PyModuleDef``, using either ``PyModule_Create`` or
+   ``PyModule_FromDefAndSpec``.
+
+   .. versionadded:: 3.5
+
+Support functions
+.................
+
+The module initialization function (if using single phase initialization) or
+a function called from a module execution slot (if using multi-phase
+initialization), can use the following functions to help initialize the module
+state:
+
+.. c:function:: int PyModule_AddObject(PyObject *module, const char *name, PyObject *value)
+
+   Add an object to *module* as *name*.  This is a convenience function which can
+   be used from the module's initialization function.  This steals a reference to
+   *value*.  Return ``-1`` on error, ``0`` on success.
+
+.. c:function:: int PyModule_AddIntConstant(PyObject *module, const char *name, long value)
+
+   Add an integer constant to *module* as *name*.  This convenience function can be
+   used from the module's initialization function. Return ``-1`` on error, ``0`` on
+   success.
+
+
+.. c:function:: int PyModule_AddStringConstant(PyObject *module, const char *name, const char *value)
+
+   Add a string constant to *module* as *name*.  This convenience function can be
+   used from the module's initialization function.  The string *value* must be
+   *NULL*-terminated.  Return ``-1`` on error, ``0`` on success.
+
+
+.. c:function:: int PyModule_AddIntMacro(PyObject *module, macro)
+
+   Add an int constant to *module*. The name and the value are taken from
+   *macro*. For example ``PyModule_AddIntMacro(module, AF_INET)`` adds the int
+   constant *AF_INET* with the value of *AF_INET* to *module*.
+   Return ``-1`` on error, ``0`` on success.
+
+
+.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro)
+
+   Add a string constant to *module*.
+
+
+Module lookup
+^^^^^^^^^^^^^
+
+Single-phase initialization creates singleton modules that can be looked up
+in the context of the current interpreter. This allows the module object to be
+retrieved later with only a reference to the module definition.
+
+These functions will not work on modules created using multi-phase initialization,
+since multiple such modules can be created from a single definition.
+
+.. c:function:: PyObject* PyState_FindModule(PyModuleDef *def)
+
+   Returns the module object that was created from *def* for the current interpreter.
+   This method requires that the module object has been attached to the interpreter state with
+   :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(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 :c:func:`PyState_FindModule`.
+
+   Only effective on modules created using single-phase initialization.
+
+   .. versionadded:: 3.3
+
+.. c:function:: int PyState_RemoveModule(PyModuleDef *def)
+
+   Removes the module object created from *def* from the interpreter state.
+
+   .. versionadded:: 3.3

third_party/python/Doc/c-api/none.rst

@@ -0,0 +1,26 @@
+.. highlightlang:: c
+
+.. _noneobject:
+
+The ``None`` Object
+-------------------
+
+.. index:: object: None
+
+Note that the :c:type:`PyTypeObject` for ``None`` is not directly exposed in the
+Python/C API.  Since ``None`` is a singleton, testing for object identity (using
+``==`` in C) is sufficient. There is no :c:func:`PyNone_Check` function for the
+same reason.
+
+
+.. c:var:: PyObject* Py_None
+
+   The Python ``None`` object, denoting lack of value.  This object has no methods.
+   It needs to be treated just like any other object with respect to reference
+   counts.
+
+
+.. c:macro:: Py_RETURN_NONE
+
+   Properly handle returning :c:data:`Py_None` from within a C function (that is,
+   increment the reference count of ``None`` and return it.)

third_party/python/Doc/c-api/number.rst

@@ -0,0 +1,283 @@
+.. highlightlang:: c
+
+.. _number:
+
+Number Protocol
+===============
+
+
+.. c:function:: int PyNumber_Check(PyObject *o)
+
+   Returns ``1`` if the object *o* provides numeric protocols, and false otherwise.
+   This function always succeeds.
+
+
+.. c:function:: PyObject* PyNumber_Add(PyObject *o1, PyObject *o2)
+
+   Returns the result of adding *o1* and *o2*, or *NULL* on failure.  This is the
+   equivalent of the Python expression ``o1 + o2``.
+
+
+.. c:function:: PyObject* PyNumber_Subtract(PyObject *o1, PyObject *o2)
+
+   Returns the result of subtracting *o2* from *o1*, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``o1 - o2``.
+
+
+.. c:function:: PyObject* PyNumber_Multiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of multiplying *o1* and *o2*, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``o1 * o2``.
+
+
+.. c:function:: PyObject* PyNumber_MatrixMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 @ o2``.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: PyObject* PyNumber_FloorDivide(PyObject *o1, PyObject *o2)
+
+   Return the floor of *o1* divided by *o2*, or *NULL* on failure.  This is
+   equivalent to the "classic" division of integers.
+
+
+.. c:function:: PyObject* PyNumber_TrueDivide(PyObject *o1, PyObject *o2)
+
+   Return a reasonable approximation for the mathematical value of *o1* divided by
+   *o2*, or *NULL* on failure.  The return value is "approximate" because binary
+   floating point numbers are approximate; it is not possible to represent all real
+   numbers in base two.  This function can return a floating point value when
+   passed two integers.
+
+
+.. c:function:: PyObject* PyNumber_Remainder(PyObject *o1, PyObject *o2)
+
+   Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``o1 % o2``.
+
+
+.. c:function:: PyObject* PyNumber_Divmod(PyObject *o1, PyObject *o2)
+
+   .. index:: builtin: divmod
+
+   See the built-in function :func:`divmod`. Returns *NULL* on failure.  This is
+   the equivalent of the Python expression ``divmod(o1, o2)``.
+
+
+.. c:function:: PyObject* PyNumber_Power(PyObject *o1, PyObject *o2, PyObject *o3)
+
+   .. index:: builtin: pow
+
+   See the built-in function :func:`pow`. Returns *NULL* on failure.  This is the
+   equivalent of the Python expression ``pow(o1, o2, o3)``, where *o3* is optional.
+   If *o3* is to be ignored, pass :c:data:`Py_None` in its place (passing *NULL* for
+   *o3* would cause an illegal memory access).
+
+
+.. c:function:: PyObject* PyNumber_Negative(PyObject *o)
+
+   Returns the negation of *o* on success, or *NULL* on failure. This is the
+   equivalent of the Python expression ``-o``.
+
+
+.. c:function:: PyObject* PyNumber_Positive(PyObject *o)
+
+   Returns *o* on success, or *NULL* on failure.  This is the equivalent of the
+   Python expression ``+o``.
+
+
+.. c:function:: PyObject* PyNumber_Absolute(PyObject *o)
+
+   .. index:: builtin: abs
+
+   Returns the absolute value of *o*, or *NULL* on failure.  This is the equivalent
+   of the Python expression ``abs(o)``.
+
+
+.. c:function:: PyObject* PyNumber_Invert(PyObject *o)
+
+   Returns the bitwise negation of *o* on success, or *NULL* on failure.  This is
+   the equivalent of the Python expression ``~o``.
+
+
+.. c:function:: PyObject* PyNumber_Lshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 << o2``.
+
+
+.. c:function:: PyObject* PyNumber_Rshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 >> o2``.
+
+
+.. c:function:: PyObject* PyNumber_And(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure.
+   This is the equivalent of the Python expression ``o1 & o2``.
+
+
+.. c:function:: PyObject* PyNumber_Xor(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o1 ^ o2``.
+
+
+.. c:function:: PyObject* PyNumber_Or(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.
+   This is the equivalent of the Python expression ``o1 | o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceAdd(PyObject *o1, PyObject *o2)
+
+   Returns the result of adding *o1* and *o2*, or *NULL* on failure.  The operation
+   is done *in-place* when *o1* supports it.  This is the equivalent of the Python
+   statement ``o1 += o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceSubtract(PyObject *o1, PyObject *o2)
+
+   Returns the result of subtracting *o2* from *o1*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 -= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of multiplying *o1* and *o2*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 *= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceMatrixMultiply(PyObject *o1, PyObject *o2)
+
+   Returns the result of matrix multiplication on *o1* and *o2*, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is
+   the equivalent of the Python statement ``o1 @= o2``.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: PyObject* PyNumber_InPlaceFloorDivide(PyObject *o1, PyObject *o2)
+
+   Returns the mathematical floor of dividing *o1* by *o2*, or *NULL* on failure.
+   The operation is done *in-place* when *o1* supports it.  This is the equivalent
+   of the Python statement ``o1 //= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceTrueDivide(PyObject *o1, PyObject *o2)
+
+   Return a reasonable approximation for the mathematical value of *o1* divided by
+   *o2*, or *NULL* on failure.  The return value is "approximate" because binary
+   floating point numbers are approximate; it is not possible to represent all real
+   numbers in base two.  This function can return a floating point value when
+   passed two integers.  The operation is done *in-place* when *o1* supports it.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceRemainder(PyObject *o1, PyObject *o2)
+
+   Returns the remainder of dividing *o1* by *o2*, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 %= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlacePower(PyObject *o1, PyObject *o2, PyObject *o3)
+
+   .. index:: builtin: pow
+
+   See the built-in function :func:`pow`. Returns *NULL* on failure.  The operation
+   is done *in-place* when *o1* supports it.  This is the equivalent of the Python
+   statement ``o1 **= o2`` when o3 is :c:data:`Py_None`, or an in-place variant of
+   ``pow(o1, o2, o3)`` otherwise. If *o3* is to be ignored, pass :c:data:`Py_None`
+   in its place (passing *NULL* for *o3* would cause an illegal memory access).
+
+
+.. c:function:: PyObject* PyNumber_InPlaceLshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of left shifting *o1* by *o2* on success, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement ``o1 <<= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceRshift(PyObject *o1, PyObject *o2)
+
+   Returns the result of right shifting *o1* by *o2* on success, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement ``o1 >>= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceAnd(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise and" of *o1* and *o2* on success and *NULL* on failure. The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 &= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceXor(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise exclusive or" of *o1* by *o2* on success, or *NULL* on
+   failure.  The operation is done *in-place* when *o1* supports it.  This is the
+   equivalent of the Python statement ``o1 ^= o2``.
+
+
+.. c:function:: PyObject* PyNumber_InPlaceOr(PyObject *o1, PyObject *o2)
+
+   Returns the "bitwise or" of *o1* and *o2* on success, or *NULL* on failure.  The
+   operation is done *in-place* when *o1* supports it.  This is the equivalent of
+   the Python statement ``o1 |= o2``.
+
+
+.. c:function:: PyObject* PyNumber_Long(PyObject *o)
+
+   .. index:: builtin: int
+
+   Returns the *o* converted to an integer object on success, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``int(o)``.
+
+
+.. c:function:: PyObject* PyNumber_Float(PyObject *o)
+
+   .. index:: builtin: float
+
+   Returns the *o* converted to a float object on success, or *NULL* on failure.
+   This is the equivalent of the Python expression ``float(o)``.
+
+
+.. c:function:: PyObject* PyNumber_Index(PyObject *o)
+
+   Returns the *o* converted to a Python int on success or *NULL* with a
+   :exc:`TypeError` exception raised on failure.
+
+
+.. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base)
+
+   Returns the integer *n* converted to base *base* as a string.  The *base*
+   argument must be one of 2, 8, 10, or 16.  For base 2, 8, or 16, the
+   returned string is prefixed with a base marker of ``'0b'``, ``'0o'``, or
+   ``'0x'``, respectively.  If *n* is not a Python int, it is converted with
+   :c:func:`PyNumber_Index` first.
+
+
+.. c:function:: Py_ssize_t PyNumber_AsSsize_t(PyObject *o, PyObject *exc)
+
+   Returns *o* converted to a Py_ssize_t value if *o* can be interpreted as an
+   integer.  If the call fails, an exception is raised and ``-1`` is returned.
+
+   If *o* can be converted to a Python int but the attempt to
+   convert to a Py_ssize_t value would raise an :exc:`OverflowError`, then the
+   *exc* argument is the type of exception that will be raised (usually
+   :exc:`IndexError` or :exc:`OverflowError`).  If *exc* is *NULL*, then the
+   exception is cleared and the value is clipped to *PY_SSIZE_T_MIN* for a negative
+   integer or *PY_SSIZE_T_MAX* for a positive integer.
+
+
+.. c:function:: int PyIndex_Check(PyObject *o)
+
+   Returns ``1`` if *o* is an index integer (has the nb_index slot of  the
+   tp_as_number structure filled in), and ``0`` otherwise.
+   This function always succeeds.

third_party/python/Doc/c-api/objbuffer.rst

@@ -0,0 +1,55 @@
+.. highlightlang:: c
+
+Old Buffer Protocol
+-------------------
+
+.. deprecated:: 3.0
+
+These functions were part of the "old buffer protocol" API in Python 2.
+In Python 3, this protocol doesn't exist anymore but the functions are still
+exposed to ease porting 2.x code.  They act as a compatibility wrapper
+around the :ref:`new buffer protocol <bufferobjects>`, but they don't give
+you control over the lifetime of the resources acquired when a buffer is
+exported.
+
+Therefore, it is recommended that you call :c:func:`PyObject_GetBuffer`
+(or the ``y*`` or ``w*`` :ref:`format codes <arg-parsing>` with the
+:c:func:`PyArg_ParseTuple` family of functions) to get a buffer view over
+an object, and :c:func:`PyBuffer_Release` when the buffer view can be released.
+
+
+.. c:function:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)
+
+   Returns a pointer to a read-only memory location usable as character-based
+   input.  The *obj* argument must support the single-segment character buffer
+   interface.  On success, returns ``0``, sets *buffer* to the memory location
+   and *buffer_len* to the buffer length.  Returns ``-1`` and sets a
+   :exc:`TypeError` on error.
+
+
+.. c:function:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
+
+   Returns a pointer to a read-only memory location containing arbitrary data.
+   The *obj* argument must support the single-segment readable buffer
+   interface.  On success, returns ``0``, sets *buffer* to the memory location
+   and *buffer_len* to the buffer length.  Returns ``-1`` and sets a
+   :exc:`TypeError` on error.
+
+
+.. c:function:: int PyObject_CheckReadBuffer(PyObject *o)
+
+   Returns ``1`` if *o* supports the single-segment readable buffer interface.
+   Otherwise returns ``0``.  This function always succeeds.
+
+   Note that this function tries to get and release a buffer, and exceptions
+   which occur while calling correspoding functions will get suppressed.
+   To get error reporting use :c:func:`PyObject_GetBuffer()` instead.
+
+
+.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
+
+   Returns a pointer to a writable memory location.  The *obj* argument must
+   support the single-segment, character buffer interface.  On success,
+   returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
+   buffer length.  Returns ``-1`` and sets a :exc:`TypeError` on error.
+

third_party/python/Doc/c-api/object.rst

@@ -0,0 +1,425 @@
+.. highlightlang:: c
+
+.. _object:
+
+Object Protocol
+===============
+
+
+.. c:var:: PyObject* Py_NotImplemented
+
+   The ``NotImplemented`` singleton, used to signal that an operation is
+   not implemented for the given type combination.
+
+
+.. c:macro:: Py_RETURN_NOTIMPLEMENTED
+
+   Properly handle returning :c:data:`Py_NotImplemented` from within a C
+   function (that is, increment the reference count of NotImplemented and
+   return it).
+
+
+.. c:function:: int PyObject_Print(PyObject *o, FILE *fp, int flags)
+
+   Print an object *o*, on file *fp*.  Returns ``-1`` on error.  The flags argument
+   is used to enable certain printing options.  The only option currently supported
+   is :const:`Py_PRINT_RAW`; if given, the :func:`str` of the object is written
+   instead of the :func:`repr`.
+
+
+.. c:function:: int PyObject_HasAttr(PyObject *o, PyObject *attr_name)
+
+   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
+   is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
+   always succeeds.
+
+   Note that exceptions which occur while calling :meth:`__getattr__` and
+   :meth:`__getattribute__` methods will get suppressed.
+   To get error reporting use :c:func:`PyObject_GetAttr()` instead.
+
+
+.. c:function:: int PyObject_HasAttrString(PyObject *o, const char *attr_name)
+
+   Returns ``1`` if *o* has the attribute *attr_name*, and ``0`` otherwise.  This
+   is equivalent to the Python expression ``hasattr(o, attr_name)``.  This function
+   always succeeds.
+
+   Note that exceptions which occur while calling :meth:`__getattr__` and
+   :meth:`__getattribute__` methods and creating a temporary string object
+   will get suppressed.
+   To get error reporting use :c:func:`PyObject_GetAttrString()` instead.
+
+
+.. c:function:: PyObject* PyObject_GetAttr(PyObject *o, PyObject *attr_name)
+
+   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
+   value on success, or *NULL* on failure.  This is the equivalent of the Python
+   expression ``o.attr_name``.
+
+
+.. c:function:: PyObject* PyObject_GetAttrString(PyObject *o, const char *attr_name)
+
+   Retrieve an attribute named *attr_name* from object *o*. Returns the attribute
+   value on success, or *NULL* on failure. This is the equivalent of the Python
+   expression ``o.attr_name``.
+
+
+.. c:function:: PyObject* PyObject_GenericGetAttr(PyObject *o, PyObject *name)
+
+   Generic attribute getter function that is meant to be put into a type
+   object's ``tp_getattro`` slot.  It looks for a descriptor in the dictionary
+   of classes in the object's MRO as well as an attribute in the object's
+   :attr:`~object.__dict__` (if present).  As outlined in :ref:`descriptors`,
+   data descriptors take preference over instance attributes, while non-data
+   descriptors don't.  Otherwise, an :exc:`AttributeError` is raised.
+
+
+.. c:function:: int PyObject_SetAttr(PyObject *o, PyObject *attr_name, PyObject *v)
+
+   Set the value of the attribute named *attr_name*, for object *o*, to the value
+   *v*. Raise an exception and return ``-1`` on failure;
+   return ``0`` on success.  This is the equivalent of the Python statement
+   ``o.attr_name = v``.
+
+   If *v* is *NULL*, the attribute is deleted, however this feature is
+   deprecated in favour of using :c:func:`PyObject_DelAttr`.
+
+
+.. c:function:: int PyObject_SetAttrString(PyObject *o, const char *attr_name, PyObject *v)
+
+   Set the value of the attribute named *attr_name*, for object *o*, to the value
+   *v*. Raise an exception and return ``-1`` on failure;
+   return ``0`` on success.  This is the equivalent of the Python statement
+   ``o.attr_name = v``.
+
+   If *v* is *NULL*, the attribute is deleted, however this feature is
+   deprecated in favour of using :c:func:`PyObject_DelAttrString`.
+
+
+.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value)
+
+   Generic attribute setter and deleter function that is meant
+   to be put into a type object's :c:member:`~PyTypeObject.tp_setattro`
+   slot.  It looks for a data descriptor in the
+   dictionary of classes in the object's MRO, and if found it takes preference
+   over setting or deleting the attribute in the instance dictionary. Otherwise, the
+   attribute is set or deleted in the object's :attr:`~object.__dict__` (if present).
+   On success, ``0`` is returned, otherwise an :exc:`AttributeError`
+   is raised and ``-1`` is returned.
+
+
+.. c:function:: int PyObject_DelAttr(PyObject *o, PyObject *attr_name)
+
+   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
+   This is the equivalent of the Python statement ``del o.attr_name``.
+
+
+.. c:function:: int PyObject_DelAttrString(PyObject *o, const char *attr_name)
+
+   Delete attribute named *attr_name*, for object *o*. Returns ``-1`` on failure.
+   This is the equivalent of the Python statement ``del o.attr_name``.
+
+
+.. c:function:: PyObject* PyObject_GenericGetDict(PyObject *o, void *context)
+
+   A generic implementation for the getter of a ``__dict__`` descriptor. It
+   creates the dictionary if necessary.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: int PyObject_GenericSetDict(PyObject *o, void *context)
+
+   A generic implementation for the setter of a ``__dict__`` descriptor. This
+   implementation does not allow the dictionary to be deleted.
+
+   .. versionadded:: 3.3
+
+
+.. c:function:: PyObject* PyObject_RichCompare(PyObject *o1, PyObject *o2, int opid)
+
+   Compare the values of *o1* and *o2* using the operation specified by *opid*,
+   which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
+   :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+   ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. This is the equivalent of
+   the Python expression ``o1 op o2``, where ``op`` is the operator corresponding
+   to *opid*. Returns the value of the comparison on success, or *NULL* on failure.
+
+
+.. c:function:: int PyObject_RichCompareBool(PyObject *o1, PyObject *o2, int opid)
+
+   Compare the values of *o1* and *o2* using the operation specified by *opid*,
+   which must be one of :const:`Py_LT`, :const:`Py_LE`, :const:`Py_EQ`,
+   :const:`Py_NE`, :const:`Py_GT`, or :const:`Py_GE`, corresponding to ``<``,
+   ``<=``, ``==``, ``!=``, ``>``, or ``>=`` respectively. Returns ``-1`` on error,
+   ``0`` if the result is false, ``1`` otherwise. This is the equivalent of the
+   Python expression ``o1 op o2``, where ``op`` is the operator corresponding to
+   *opid*.
+
+.. note::
+   If *o1* and *o2* are the same object, :c:func:`PyObject_RichCompareBool`
+   will always return ``1`` for :const:`Py_EQ` and ``0`` for :const:`Py_NE`.
+
+.. c:function:: PyObject* PyObject_Repr(PyObject *o)
+
+   .. index:: builtin: repr
+
+   Compute a string representation of object *o*.  Returns the string
+   representation on success, *NULL* on failure.  This is the equivalent of the
+   Python expression ``repr(o)``.  Called by the :func:`repr` built-in function.
+
+   .. versionchanged:: 3.4
+      This function now includes a debug assertion to help ensure that it
+      does not silently discard an active exception.
+
+.. c:function:: PyObject* PyObject_ASCII(PyObject *o)
+
+   .. index:: builtin: ascii
+
+   As :c:func:`PyObject_Repr`, compute a string representation of object *o*, but
+   escape the non-ASCII characters in the string returned by
+   :c:func:`PyObject_Repr` with ``\x``, ``\u`` or ``\U`` escapes.  This generates
+   a string similar to that returned by :c:func:`PyObject_Repr` in Python 2.
+   Called by the :func:`ascii` built-in function.
+
+   .. index:: string; PyObject_Str (C function)
+
+
+.. c:function:: PyObject* PyObject_Str(PyObject *o)
+
+   Compute a string representation of object *o*.  Returns the string
+   representation on success, *NULL* on failure.  This is the equivalent of the
+   Python expression ``str(o)``.  Called by the :func:`str` built-in function
+   and, therefore, by the :func:`print` function.
+
+   .. versionchanged:: 3.4
+      This function now includes a debug assertion to help ensure that it
+      does not silently discard an active exception.
+
+.. c:function:: PyObject* PyObject_Bytes(PyObject *o)
+
+   .. index:: builtin: bytes
+
+   Compute a bytes representation of object *o*.  *NULL* is returned on
+   failure and a bytes object on success.  This is equivalent to the Python
+   expression ``bytes(o)``, when *o* is not an integer.  Unlike ``bytes(o)``,
+   a TypeError is raised when *o* is an integer instead of a zero-initialized
+   bytes object.
+
+
+.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls)
+
+   Return ``1`` if the class *derived* is identical to or derived from the class
+   *cls*, otherwise return ``0``.  In case of an error, return ``-1``.
+
+   If *cls* is a tuple, the check will be done against every entry in *cls*.
+   The result will be ``1`` when at least one of the checks returns ``1``,
+   otherwise it will be ``0``.
+
+   If *cls* has a :meth:`~class.__subclasscheck__` method, it will be called to
+   determine the subclass status as described in :pep:`3119`.  Otherwise,
+   *derived* is a subclass of *cls* if it is a direct or indirect subclass,
+   i.e. contained in ``cls.__mro__``.
+
+   Normally only class objects, i.e. instances of :class:`type` or a derived
+   class, are considered classes.  However, objects can override this by having
+   a :attr:`__bases__` attribute (which must be a tuple of base classes).
+
+
+.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls)
+
+   Return ``1`` if *inst* is an instance of the class *cls* or a subclass of
+   *cls*, or ``0`` if not.  On error, returns ``-1`` and sets an exception.
+
+   If *cls* is a tuple, the check will be done against every entry in *cls*.
+   The result will be ``1`` when at least one of the checks returns ``1``,
+   otherwise it will be ``0``.
+
+   If *cls* has a :meth:`~class.__instancecheck__` method, it will be called to
+   determine the subclass status as described in :pep:`3119`.  Otherwise, *inst*
+   is an instance of *cls* if its class is a subclass of *cls*.
+
+   An instance *inst* can override what is considered its class by having a
+   :attr:`__class__` attribute.
+
+   An object *cls* can override if it is considered a class, and what its base
+   classes are, by having a :attr:`__bases__` attribute (which must be a tuple
+   of base classes).
+
+
+.. c:function:: int PyCallable_Check(PyObject *o)
+
+   Determine if the object *o* is callable.  Return ``1`` if the object is callable
+   and ``0`` otherwise.  This function always succeeds.
+
+
+.. c:function:: PyObject* PyObject_Call(PyObject *callable_object, PyObject *args, PyObject *kw)
+
+   Call a callable Python object *callable_object*, with arguments given by the
+   tuple *args*, and named arguments given by the dictionary *kw*. If no named
+   arguments are needed, *kw* may be *NULL*. *args* must not be *NULL*, use an
+   empty tuple if no arguments are needed. Returns the result of the call on
+   success, or *NULL* on failure.  This is the equivalent of the Python expression
+   ``callable_object(*args, **kw)``.
+
+
+.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args)
+
+   Call a callable Python object *callable_object*, with arguments given by the
+   tuple *args*.  If no arguments are needed, then *args* may be *NULL*.  Returns
+   the result of the call on success, or *NULL* on failure.  This is the equivalent
+   of the Python expression ``callable_object(*args)``.
+
+
+.. 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
+   string.  The format may be *NULL*, indicating that no arguments are provided.
+   Returns the result of the call on success, or *NULL* on failure.  This is the
+   equivalent of the Python expression ``callable(*args)``. Note that if you only
+   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, 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
+   string that should  produce a tuple.  The format may be *NULL*, indicating that
+   no arguments are provided. Returns the result of the call on success, or *NULL*
+   on failure.  This is the equivalent of the Python expression ``o.method(args)``.
+   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)
+
+   Call a callable Python object *callable*, with a variable number of
+   :c:type:`PyObject\*` arguments.  The arguments are provided as a variable number
+   of parameters followed by *NULL*. Returns the result of the call on success, or
+   *NULL* on failure.
+
+
+.. c:function:: PyObject* PyObject_CallMethodObjArgs(PyObject *o, PyObject *name, ..., NULL)
+
+   Calls a method of the object *o*, where the name of the method is given as a
+   Python string object in *name*.  It is called with a variable number of
+   :c:type:`PyObject\*` arguments.  The arguments are provided as a variable number
+   of parameters followed by *NULL*. Returns the result of the call on success, or
+   *NULL* on failure.
+
+
+.. c:function:: Py_hash_t PyObject_Hash(PyObject *o)
+
+   .. index:: builtin: hash
+
+   Compute and return the hash value of an object *o*.  On failure, return ``-1``.
+   This is the equivalent of the Python expression ``hash(o)``.
+
+   .. versionchanged:: 3.2
+      The return type is now Py_hash_t.  This is a signed integer the same size
+      as Py_ssize_t.
+
+
+.. c:function:: Py_hash_t PyObject_HashNotImplemented(PyObject *o)
+
+   Set a :exc:`TypeError` indicating that ``type(o)`` is not hashable and return ``-1``.
+   This function receives special treatment when stored in a ``tp_hash`` slot,
+   allowing a type to explicitly indicate to the interpreter that it is not
+   hashable.
+
+
+.. c:function:: int PyObject_IsTrue(PyObject *o)
+
+   Returns ``1`` if the object *o* is considered to be true, and ``0`` otherwise.
+   This is equivalent to the Python expression ``not not o``.  On failure, return
+   ``-1``.
+
+
+.. c:function:: int PyObject_Not(PyObject *o)
+
+   Returns ``0`` if the object *o* is considered to be true, and ``1`` otherwise.
+   This is equivalent to the Python expression ``not o``.  On failure, return
+   ``-1``.
+
+
+.. c:function:: PyObject* PyObject_Type(PyObject *o)
+
+   .. index:: builtin: type
+
+   When *o* is non-*NULL*, returns a type object corresponding to the object type
+   of object *o*. On failure, raises :exc:`SystemError` and returns *NULL*.  This
+   is equivalent to the Python expression ``type(o)``. This function increments the
+   reference count of the return value. There's really no reason to use this
+   function instead of the common expression ``o->ob_type``, which returns a
+   pointer of type :c:type:`PyTypeObject\*`, except when the incremented reference
+   count is needed.
+
+
+.. c:function:: int PyObject_TypeCheck(PyObject *o, PyTypeObject *type)
+
+   Return true if the object *o* is of type *type* or a subtype of *type*.  Both
+   parameters must be non-*NULL*.
+
+
+.. c:function:: Py_ssize_t PyObject_Size(PyObject *o)
+               Py_ssize_t PyObject_Length(PyObject *o)
+
+   .. index:: builtin: len
+
+   Return the length of object *o*.  If the object *o* provides either the sequence
+   and mapping protocols, the sequence length is returned.  On error, ``-1`` is
+   returned.  This is the equivalent to the Python expression ``len(o)``.
+
+
+.. c:function:: Py_ssize_t PyObject_LengthHint(PyObject *o, Py_ssize_t default)
+
+   Return an estimated length for the object *o*. First try to return its
+   actual length, then an estimate using :meth:`~object.__length_hint__`, and
+   finally return the default value. On error return ``-1``. This is the
+   equivalent to the Python expression ``operator.length_hint(o, default)``.
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
+
+   Return element of *o* corresponding to the object *key* or *NULL* on failure.
+   This is the equivalent of the Python expression ``o[key]``.
+
+
+.. c:function:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)
+
+   Map the object *key* to the value *v*.  Raise an exception and
+   return ``-1`` on failure; return ``0`` on success.  This is the
+   equivalent of the Python statement ``o[key] = v``.
+
+
+.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key)
+
+   Remove the mapping for the object *key* from the object *o*.  Return ``-1``
+   on failure.  This is equivalent to the Python statement ``del o[key]``.
+
+
+.. c:function:: PyObject* PyObject_Dir(PyObject *o)
+
+   This is equivalent to the Python expression ``dir(o)``, returning a (possibly
+   empty) list of strings appropriate for the object argument, or *NULL* if there
+   was an error.  If the argument is *NULL*, this is like the Python ``dir()``,
+   returning the names of the current locals; in this case, if no execution frame
+   is active then *NULL* is returned but :c:func:`PyErr_Occurred` will return false.
+
+
+.. c:function:: PyObject* PyObject_GetIter(PyObject *o)
+
+   This is equivalent to the Python expression ``iter(o)``. It returns a new
+   iterator for the object argument, or the object  itself if the object is already
+   an iterator.  Raises :exc:`TypeError` and returns *NULL* if the object cannot be
+   iterated.

third_party/python/Doc/c-api/objimpl.rst

@@ -0,0 +1,17 @@
+.. highlightlang:: c
+
+.. _newtypes:
+
+*****************************
+Object Implementation Support
+*****************************
+
+This chapter describes the functions, types, and macros used when defining new
+object types.
+
+.. toctree::
+
+   allocation.rst
+   structures.rst
+   typeobj.rst
+   gcsupport.rst

third_party/python/Doc/c-api/refcounting.rst

@@ -0,0 +1,73 @@
+.. highlightlang:: c
+
+
+.. _countingrefs:
+
+******************
+Reference Counting
+******************
+
+The macros in this section are used for managing reference counts of Python
+objects.
+
+
+.. c:function:: void Py_INCREF(PyObject *o)
+
+   Increment the reference count for object *o*.  The object must not be *NULL*; if
+   you aren't sure that it isn't *NULL*, use :c:func:`Py_XINCREF`.
+
+
+.. c:function:: void Py_XINCREF(PyObject *o)
+
+   Increment the reference count for object *o*.  The object may be *NULL*, in
+   which case the macro has no effect.
+
+
+.. c:function:: void Py_DECREF(PyObject *o)
+
+   Decrement the reference count for object *o*.  The object must not be *NULL*; if
+   you aren't sure that it isn't *NULL*, use :c:func:`Py_XDECREF`.  If the reference
+   count reaches zero, the object's type's deallocation function (which must not be
+   *NULL*) is invoked.
+
+   .. warning::
+
+      The deallocation function can cause arbitrary Python code to be invoked (e.g.
+      when a class instance with a :meth:`__del__` method is deallocated).  While
+      exceptions in such code are not propagated, the executed code has free access to
+      all Python global variables.  This means that any object that is reachable from
+      a global variable should be in a consistent state before :c:func:`Py_DECREF` is
+      invoked.  For example, code to delete an object from a list should copy a
+      reference to the deleted object in a temporary variable, update the list data
+      structure, and then call :c:func:`Py_DECREF` for the temporary variable.
+
+
+.. c:function:: void Py_XDECREF(PyObject *o)
+
+   Decrement the reference count for object *o*.  The object may be *NULL*, in
+   which case the macro has no effect; otherwise the effect is the same as for
+   :c:func:`Py_DECREF`, and the same warning applies.
+
+
+.. c:function:: void Py_CLEAR(PyObject *o)
+
+   Decrement the reference count for object *o*.  The object may be *NULL*, in
+   which case the macro has no effect; otherwise the effect is the same as for
+   :c:func:`Py_DECREF`, except that the argument is also set to *NULL*.  The warning
+   for :c:func:`Py_DECREF` does not apply with respect to the object passed because
+   the macro carefully uses a temporary variable and sets the argument to *NULL*
+   before decrementing its reference count.
+
+   It is a good idea to use this macro whenever decrementing the value of a
+   variable that might be traversed during garbage collection.
+
+
+The following functions are for runtime dynamic embedding of Python:
+``Py_IncRef(PyObject *o)``, ``Py_DecRef(PyObject *o)``. They are
+simply exported function versions of :c:func:`Py_XINCREF` and
+:c:func:`Py_XDECREF`, respectively.
+
+The following functions or macros are only for use within the interpreter core:
+:c:func:`_Py_Dealloc`, :c:func:`_Py_ForgetReference`, :c:func:`_Py_NewReference`,
+as well as the global variable :c:data:`_Py_RefTotal`.
+

third_party/python/Doc/c-api/reflection.rst

@@ -0,0 +1,49 @@
+.. highlightlang:: c
+
+.. _reflection:
+
+Reflection
+==========
+
+.. c:function:: PyObject* PyEval_GetBuiltins()
+
+   Return a dictionary of the builtins in the current execution frame,
+   or the interpreter of the thread state if no frame is currently executing.
+
+
+.. c:function:: PyObject* PyEval_GetLocals()
+
+   Return a dictionary of the local variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+
+
+.. c:function:: PyObject* PyEval_GetGlobals()
+
+   Return a dictionary of the global variables in the current execution frame,
+   or *NULL* if no frame is currently executing.
+
+
+.. c:function:: PyFrameObject* PyEval_GetFrame()
+
+   Return the current thread state's frame, which is *NULL* if no frame is
+   currently executing.
+
+
+.. c:function:: int PyFrame_GetLineNumber(PyFrameObject *frame)
+
+   Return the line number that *frame* is currently executing.
+
+
+.. c:function:: const char* PyEval_GetFuncName(PyObject *func)
+
+   Return the name of *func* if it is a function, class or instance object, else the
+   name of *func*\s type.
+
+
+.. c:function:: const char* PyEval_GetFuncDesc(PyObject *func)
+
+   Return a description string, depending on the type of *func*.
+   Return values include "()" for functions and methods, " constructor",
+   " instance", and " object".  Concatenated with the result of
+   :c:func:`PyEval_GetFuncName`, the result will be a description of
+   *func*.

third_party/python/Doc/c-api/sequence.rst

@@ -0,0 +1,169 @@
+.. highlightlang:: c
+
+.. _sequence:
+
+Sequence Protocol
+=================
+
+
+.. c:function:: int PySequence_Check(PyObject *o)
+
+   Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.
+   Note that it returns ``1`` for Python classes with a :meth:`__getitem__`
+   method unless they are :class:`dict` subclasses since in general case it
+   is impossible to determine what the type of keys it supports.  This
+   function always succeeds.
+
+
+.. c:function:: Py_ssize_t PySequence_Size(PyObject *o)
+               Py_ssize_t PySequence_Length(PyObject *o)
+
+   .. index:: builtin: len
+
+   Returns the number of objects in sequence *o* on success, and ``-1`` on
+   failure.  This is equivalent to the Python expression ``len(o)``.
+
+
+.. c:function:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
+
+   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
+   This is the equivalent of the Python expression ``o1 + o2``.
+
+
+.. c:function:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)
+
+   Return the result of repeating sequence object *o* *count* times, or *NULL* on
+   failure.  This is the equivalent of the Python expression ``o * count``.
+
+
+.. c:function:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
+
+   Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.
+   The operation is done *in-place* when *o1* supports it.  This is the equivalent
+   of the Python expression ``o1 += o2``.
+
+
+.. c:function:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)
+
+   Return the result of repeating sequence object *o* *count* times, or *NULL* on
+   failure.  The operation is done *in-place* when *o* supports it.  This is the
+   equivalent of the Python expression ``o *= count``.
+
+
+.. c:function:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)
+
+   Return the *i*\ th element of *o*, or *NULL* on failure. This is the equivalent of
+   the Python expression ``o[i]``.
+
+
+.. c:function:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
+
+   Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on
+   failure. This is the equivalent of the Python expression ``o[i1:i2]``.
+
+
+.. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
+
+   Assign object *v* to the *i*\ th element of *o*.  Raise an exception
+   and return ``-1`` on failure; return ``0`` on success.  This
+   is the equivalent of the Python statement ``o[i] = v``.  This function *does
+   not* steal a reference to *v*.
+
+   If *v* is *NULL*, the element is deleted, however this feature is
+   deprecated in favour of using :c:func:`PySequence_DelItem`.
+
+
+.. c:function:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)
+
+   Delete the *i*\ th element of object *o*.  Returns ``-1`` on failure.  This is the
+   equivalent of the Python statement ``del o[i]``.
+
+
+.. c:function:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)
+
+   Assign the sequence object *v* to the slice in sequence object *o* from *i1* to
+   *i2*.  This is the equivalent of the Python statement ``o[i1:i2] = v``.
+
+
+.. c:function:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)
+
+   Delete the slice in sequence object *o* from *i1* to *i2*.  Returns ``-1`` on
+   failure.  This is the equivalent of the Python statement ``del o[i1:i2]``.
+
+
+.. c:function:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
+
+   Return the number of occurrences of *value* in *o*, that is, return the number
+   of keys for which ``o[key] == value``.  On failure, return ``-1``.  This is
+   equivalent to the Python expression ``o.count(value)``.
+
+
+.. c:function:: int PySequence_Contains(PyObject *o, PyObject *value)
+
+   Determine if *o* contains *value*.  If an item in *o* is equal to *value*,
+   return ``1``, otherwise return ``0``. On error, return ``-1``.  This is
+   equivalent to the Python expression ``value in o``.
+
+
+.. c:function:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)
+
+   Return the first index *i* for which ``o[i] == value``.  On error, return
+   ``-1``.    This is equivalent to the Python expression ``o.index(value)``.
+
+
+.. c:function:: PyObject* PySequence_List(PyObject *o)
+
+   Return a list object with the same contents as the sequence or iterable *o*,
+   or *NULL* on failure.  The returned list is guaranteed to be new.  This is
+   equivalent to the Python expression ``list(o)``.
+
+
+.. c:function:: PyObject* PySequence_Tuple(PyObject *o)
+
+   .. index:: builtin: tuple
+
+   Return a tuple object with the same contents as the sequence or iterable *o*,
+   or *NULL* on failure.  If *o* is a tuple, a new reference will be returned,
+   otherwise a tuple will be constructed with the appropriate contents.  This is
+   equivalent to the Python expression ``tuple(o)``.
+
+
+.. c:function:: PyObject* PySequence_Fast(PyObject *o, const char *m)
+
+   Return the sequence or iterable *o* as a list, unless it is already a tuple or list, in
+   which case *o* is returned.  Use :c:func:`PySequence_Fast_GET_ITEM` to access
+   the members of the result.  Returns *NULL* on failure.  If the object is not
+   a sequence or iterable, raises :exc:`TypeError` with *m* as the message text.
+
+
+.. c:function:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
+
+   Returns the length of *o*, assuming that *o* was returned by
+   :c:func:`PySequence_Fast` and that *o* is not *NULL*.  The size can also be
+   gotten by calling :c:func:`PySequence_Size` on *o*, but
+   :c:func:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list
+   or tuple.
+
+
+.. c:function:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)
+
+   Return the *i*\ th element of *o*, assuming that *o* was returned by
+   :c:func:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
+
+
+.. c:function:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
+
+   Return the underlying array of PyObject pointers.  Assumes that *o* was returned
+   by :c:func:`PySequence_Fast` and *o* is not *NULL*.
+
+   Note, if a list gets resized, the reallocation may relocate the items array.
+   So, only use the underlying array pointer in contexts where the sequence
+   cannot change.
+
+
+.. c:function:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)
+
+   Return the *i*\ th element of *o* or *NULL* on failure. Macro form of
+   :c:func:`PySequence_GetItem` but without checking that
+   :c:func:`PySequence_Check` on *o* is true and without adjustment for negative
+   indices.

third_party/python/Doc/c-api/set.rst

@@ -0,0 +1,166 @@
+.. highlightlang:: c
+
+.. _setobjects:
+
+Set Objects
+-----------
+
+.. sectionauthor:: Raymond D. Hettinger <python@rcn.com>
+
+
+.. index::
+   object: set
+   object: frozenset
+
+This section details the public API for :class:`set` and :class:`frozenset`
+objects.  Any functionality not listed below is best accessed using the either
+the abstract object protocol (including :c:func:`PyObject_CallMethod`,
+:c:func:`PyObject_RichCompareBool`, :c:func:`PyObject_Hash`,
+:c:func:`PyObject_Repr`, :c:func:`PyObject_IsTrue`, :c:func:`PyObject_Print`, and
+:c:func:`PyObject_GetIter`) or the abstract number protocol (including
+:c:func:`PyNumber_And`, :c:func:`PyNumber_Subtract`, :c:func:`PyNumber_Or`,
+:c:func:`PyNumber_Xor`, :c:func:`PyNumber_InPlaceAnd`,
+:c:func:`PyNumber_InPlaceSubtract`, :c:func:`PyNumber_InPlaceOr`, and
+:c:func:`PyNumber_InPlaceXor`).
+
+
+.. c:type:: PySetObject
+
+   This subtype of :c:type:`PyObject` is used to hold the internal data for both
+   :class:`set` and :class:`frozenset` objects.  It is like a :c:type:`PyDictObject`
+   in that it is a fixed size for small sets (much like tuple storage) and will
+   point to a separate, variable sized block of memory for medium and large sized
+   sets (much like list storage). None of the fields of this structure should be
+   considered public and are subject to change.  All access should be done through
+   the documented API rather than by manipulating the values in the structure.
+
+
+.. c:var:: PyTypeObject PySet_Type
+
+   This is an instance of :c:type:`PyTypeObject` representing the Python
+   :class:`set` type.
+
+
+.. c:var:: PyTypeObject PyFrozenSet_Type
+
+   This is an instance of :c:type:`PyTypeObject` representing the Python
+   :class:`frozenset` type.
+
+The following type check macros work on pointers to any Python object. Likewise,
+the constructor functions work with any iterable Python object.
+
+
+.. c:function:: int PySet_Check(PyObject *p)
+
+   Return true if *p* is a :class:`set` object or an instance of a subtype.
+
+.. c:function:: int PyFrozenSet_Check(PyObject *p)
+
+   Return true if *p* is a :class:`frozenset` object or an instance of a
+   subtype.
+
+.. c:function:: int PyAnySet_Check(PyObject *p)
+
+   Return true if *p* is a :class:`set` object, a :class:`frozenset` object, or an
+   instance of a subtype.
+
+
+.. c:function:: int PyAnySet_CheckExact(PyObject *p)
+
+   Return true if *p* is a :class:`set` object or a :class:`frozenset` object but
+   not an instance of a subtype.
+
+
+.. c:function:: int PyFrozenSet_CheckExact(PyObject *p)
+
+   Return true if *p* is a :class:`frozenset` object but not an instance of a
+   subtype.
+
+
+.. c:function:: PyObject* PySet_New(PyObject *iterable)
+
+   Return a new :class:`set` containing objects returned by the *iterable*.  The
+   *iterable* may be *NULL* to create a new empty set.  Return the new set on
+   success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is not
+   actually iterable.  The constructor is also useful for copying a set
+   (``c=set(s)``).
+
+
+.. c:function:: PyObject* PyFrozenSet_New(PyObject *iterable)
+
+   Return a new :class:`frozenset` containing objects returned by the *iterable*.
+   The *iterable* may be *NULL* to create a new empty frozenset.  Return the new
+   set on success or *NULL* on failure.  Raise :exc:`TypeError` if *iterable* is
+   not actually iterable.
+
+
+The following functions and macros are available for instances of :class:`set`
+or :class:`frozenset` or instances of their subtypes.
+
+
+.. c:function:: Py_ssize_t PySet_Size(PyObject *anyset)
+
+   .. index:: builtin: len
+
+   Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to
+   ``len(anyset)``.  Raises a :exc:`PyExc_SystemError` if *anyset* is not a
+   :class:`set`, :class:`frozenset`, or an instance of a subtype.
+
+
+.. c:function:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
+
+   Macro form of :c:func:`PySet_Size` without error checking.
+
+
+.. c:function:: int PySet_Contains(PyObject *anyset, PyObject *key)
+
+   Return ``1`` if found, ``0`` if not found, and ``-1`` if an error is encountered.  Unlike
+   the Python :meth:`__contains__` method, this function does not automatically
+   convert unhashable sets into temporary frozensets.  Raise a :exc:`TypeError` if
+   the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a
+   :class:`set`, :class:`frozenset`, or an instance of a subtype.
+
+
+.. c:function:: int PySet_Add(PyObject *set, PyObject *key)
+
+   Add *key* to a :class:`set` instance.  Also works with :class:`frozenset`
+   instances (like :c:func:`PyTuple_SetItem` it can be used to fill-in the values
+   of brand new frozensets before they are exposed to other code).  Return ``0`` on
+   success or ``-1`` on failure. Raise a :exc:`TypeError` if the *key* is
+   unhashable. Raise a :exc:`MemoryError` if there is no room to grow.  Raise a
+   :exc:`SystemError` if *set* is not an instance of :class:`set` or its
+   subtype.
+
+
+The following functions are available for instances of :class:`set` or its
+subtypes but not for instances of :class:`frozenset` or its subtypes.
+
+
+.. c:function:: int PySet_Discard(PyObject *set, PyObject *key)
+
+   Return ``1`` if found and removed, ``0`` if not found (no action taken), and ``-1`` if an
+   error is encountered.  Does not raise :exc:`KeyError` for missing keys.  Raise a
+   :exc:`TypeError` if the *key* is unhashable.  Unlike the Python :meth:`~set.discard`
+   method, this function does not automatically convert unhashable sets into
+   temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is not an
+   instance of :class:`set` or its subtype.
+
+
+.. c:function:: PyObject* PySet_Pop(PyObject *set)
+
+   Return a new reference to an arbitrary object in the *set*, and removes the
+   object from the *set*.  Return *NULL* on failure.  Raise :exc:`KeyError` if the
+   set is empty. Raise a :exc:`SystemError` if *set* is not an instance of
+   :class:`set` or its subtype.
+
+
+.. c:function:: int PySet_Clear(PyObject *set)
+
+   Empty an existing set of all elements.
+
+
+.. c:function:: int PySet_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+
+   .. versionadded:: 3.3

third_party/python/Doc/c-api/slice.rst

@@ -0,0 +1,69 @@
+.. highlightlang:: c
+
+.. _slice-objects:
+
+Slice Objects
+-------------
+
+
+.. c:var:: PyTypeObject PySlice_Type
+
+   The type object for slice objects.  This is the same as :class:`slice` in the
+   Python layer.
+
+
+.. c:function:: int PySlice_Check(PyObject *ob)
+
+   Return true if *ob* is a slice object; *ob* must not be *NULL*.
+
+
+.. c:function:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)
+
+   Return a new slice object with the given values.  The *start*, *stop*, and
+   *step* parameters are used as the values of the slice object attributes of
+   the same names.  Any of the values may be *NULL*, in which case the
+   ``None`` will be used for the corresponding attribute.  Return *NULL* if
+   the new object could not be allocated.
+
+
+.. c:function:: int PySlice_GetIndices(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)
+
+   Retrieve the start, stop and step indices from the slice object *slice*,
+   assuming a sequence of length *length*. Treats indices greater than
+   *length* as errors.
+
+   Returns ``0`` on success and ``-1`` on error with no exception set (unless one of
+   the indices was not :const:`None` and failed to be converted to an integer,
+   in which case ``-1`` is returned with an exception set).
+
+   You probably do not want to use this function.
+
+   .. versionchanged:: 3.2
+      The parameter type for the *slice* parameter was ``PySliceObject*``
+      before.
+
+
+.. c:function:: int PySlice_GetIndicesEx(PyObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step, Py_ssize_t *slicelength)
+
+   Usable replacement for :c:func:`PySlice_GetIndices`.  Retrieve the start,
+   stop, and step indices from the slice object *slice* assuming a sequence of
+   length *length*, and store the length of the slice in *slicelength*.  Out
+   of bounds indices are clipped in a manner consistent with the handling of
+   normal slices.
+
+   Returns ``0`` on success and ``-1`` on error with exception set.
+
+   .. versionchanged:: 3.2
+      The parameter type for the *slice* parameter was ``PySliceObject*``
+      before.
+
+
+Ellipsis Object
+---------------
+
+
+.. c:var:: PyObject *Py_Ellipsis
+
+   The Python ``Ellipsis`` object.  This object has no methods.  It needs to be
+   treated just like any other object with respect to reference counts.  Like
+   :c:data:`Py_None` it is a singleton object.

third_party/python/Doc/c-api/stable.rst

@@ -0,0 +1,38 @@
+.. highlightlang:: c
+
+.. _stable:
+
+***********************************
+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, rather than changing
+existing API or removing API (although some interfaces do get removed after
+being deprecated first).
+
+Unfortunately, the API compatibility does not extend to binary compatibility
+(the ABI). The reason is primarily the evolution of struct definitions, where
+addition of a new field, or changing the type of a field, might not break the
+API, but can break the ABI.  As a consequence, extension modules need to be
+recompiled for every Python release (although an exception is possible on Unix
+when none of the affected interfaces are used). In addition, on Windows,
+extension modules link with a specific pythonXY.dll and need to be recompiled to
+link with a newer one.
+
+Since Python 3.2, a subset of the API has been declared to guarantee a stable
+ABI. Extension modules wishing to use this API (called "limited API") need to
+define ``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.
+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.
+
+As of Python 3.2, the set of functions available to the limited API is
+documented in :pep:`384`.  In the C API documentation, API elements that are not
+part of the limited API are marked as "Not part of the limited API."

third_party/python/Doc/c-api/structures.rst

@@ -0,0 +1,337 @@
+.. highlightlang:: c
+
+.. _common-structs:
+
+Common Object Structures
+========================
+
+There are a large number of structures which are used in the definition of
+object types for Python.  This section describes these structures and how they
+are used.
+
+All Python objects ultimately share a small number of fields at the beginning
+of the object's representation in memory.  These are represented by the
+:c:type:`PyObject` and :c:type:`PyVarObject` types, which are defined, in turn,
+by the expansions of some macros also used, whether directly or indirectly, in
+the definition of all other Python objects.
+
+
+.. c:type:: PyObject
+
+   All object types are extensions of this type.  This is a type which
+   contains the information Python needs to treat a pointer to an object as an
+   object.  In a normal "release" build, it contains only the object's
+   reference count and a pointer to the corresponding type object.
+   Nothing is actually declared to be a :c:type:`PyObject`, but every pointer
+   to a Python object can be cast to a :c:type:`PyObject*`.  Access to the
+   members must be done by using the macros :c:macro:`Py_REFCNT` and
+   :c:macro:`Py_TYPE`.
+
+
+.. c:type:: PyVarObject
+
+   This is an extension of :c:type:`PyObject` that adds the :attr:`ob_size`
+   field.  This is only used for objects that have some notion of *length*.
+   This type does not often appear in the Python/C API.
+   Access to the members must be done by using the macros
+   :c:macro:`Py_REFCNT`, :c:macro:`Py_TYPE`, and :c:macro:`Py_SIZE`.
+
+
+.. c:macro:: PyObject_HEAD
+
+   This is a macro used when declaring new types which represent objects
+   without a varying length.  The PyObject_HEAD macro expands to::
+
+      PyObject ob_base;
+
+   See documentation of :c:type:`PyObject` above.
+
+
+.. c:macro:: PyObject_VAR_HEAD
+
+   This is a macro used when declaring new types which represent objects
+   with a length that varies from instance to instance.
+   The PyObject_VAR_HEAD macro expands to::
+
+      PyVarObject ob_base;
+
+   See documentation of :c:type:`PyVarObject` above.
+
+
+.. c:macro:: Py_TYPE(o)
+
+   This macro is used to access the :attr:`ob_type` member of a Python object.
+   It expands to::
+
+      (((PyObject*)(o))->ob_type)
+
+
+.. c:macro:: Py_REFCNT(o)
+
+   This macro is used to access the :attr:`ob_refcnt` member of a Python
+   object.
+   It expands to::
+
+      (((PyObject*)(o))->ob_refcnt)
+
+
+.. c:macro:: Py_SIZE(o)
+
+   This macro is used to access the :attr:`ob_size` member of a Python object.
+   It expands to::
+
+      (((PyVarObject*)(o))->ob_size)
+
+
+.. c:macro:: PyObject_HEAD_INIT(type)
+
+   This is a macro which expands to initialization values for a new
+   :c:type:`PyObject` type.  This macro expands to::
+
+      _PyObject_EXTRA_INIT
+      1, type,
+
+
+.. c:macro:: PyVarObject_HEAD_INIT(type, size)
+
+   This is a macro which expands to initialization values for a new
+   :c:type:`PyVarObject` type, including the :attr:`ob_size` field.
+   This macro expands to::
+
+      _PyObject_EXTRA_INIT
+      1, type, size,
+
+
+.. c:type:: PyCFunction
+
+   Type of the functions used to implement most Python callables in C.
+   Functions of this type take two :c:type:`PyObject\*` parameters and return
+   one such value.  If the return value is *NULL*, an exception shall have
+   been set.  If not *NULL*, the return value is interpreted as the return
+   value of the function as exposed in Python.  The function must return a new
+   reference.
+
+
+.. c:type:: PyCFunctionWithKeywords
+
+   Type of the functions used to implement Python callables in C that take
+   keyword arguments: they take three :c:type:`PyObject\*` parameters and return
+   one such value.  See :c:type:`PyCFunction` above for the meaning of the return
+   value.
+
+
+.. c:type:: PyMethodDef
+
+   Structure used to describe a method of an extension type.  This structure has
+   four fields:
+
+   +------------------+-------------+-------------------------------+
+   | Field            | C Type      | Meaning                       |
+   +==================+=============+===============================+
+   | :attr:`ml_name`  | char \*     | name of the method            |
+   +------------------+-------------+-------------------------------+
+   | :attr:`ml_meth`  | PyCFunction | pointer to the C              |
+   |                  |             | implementation                |
+   +------------------+-------------+-------------------------------+
+   | :attr:`ml_flags` | int         | flag bits indicating how the  |
+   |                  |             | call should be constructed    |
+   +------------------+-------------+-------------------------------+
+   | :attr:`ml_doc`   | char \*     | points to the contents of the |
+   |                  |             | docstring                     |
+   +------------------+-------------+-------------------------------+
+
+The :attr:`ml_meth` is a C function pointer.  The functions may be of different
+types, but they always return :c:type:`PyObject\*`.  If the function is not of
+the :c:type:`PyCFunction`, the compiler will require a cast in the method table.
+Even though :c:type:`PyCFunction` defines the first parameter as
+:c:type:`PyObject\*`, it is common that the method implementation uses the
+specific C type of the *self* object.
+
+The :attr:`ml_flags` field is a bitfield which can include the following flags.
+The individual flags indicate either a calling convention or a binding
+convention.  Of the calling convention flags, only :const:`METH_VARARGS` and
+:const:`METH_KEYWORDS` can be combined. Any of the calling convention flags
+can be combined with a binding flag.
+
+
+.. data:: METH_VARARGS
+
+   This is the typical calling convention, where the methods have the type
+   :c:type:`PyCFunction`. The function expects two :c:type:`PyObject\*` values.
+   The first one is the *self* object for methods; for module functions, it is
+   the module object.  The second parameter (often called *args*) is a tuple
+   object representing all arguments. This parameter is typically processed
+   using :c:func:`PyArg_ParseTuple` or :c:func:`PyArg_UnpackTuple`.
+
+
+.. data:: METH_KEYWORDS
+
+   Methods with these flags must be of type :c:type:`PyCFunctionWithKeywords`.
+   The function expects three parameters: *self*, *args*, and a dictionary of
+   all the keyword arguments.  The flag must be combined with
+   :const:`METH_VARARGS`, and the parameters are typically processed using
+   :c:func:`PyArg_ParseTupleAndKeywords`.
+
+
+.. data:: METH_NOARGS
+
+   Methods without parameters don't need to check whether arguments are given if
+   they are listed with the :const:`METH_NOARGS` flag.  They need to be of type
+   :c:type:`PyCFunction`.  The first parameter is typically named *self* and will
+   hold a reference to the module or object instance.  In all cases the second
+   parameter will be *NULL*.
+
+
+.. data:: METH_O
+
+   Methods with a single object argument can be listed with the :const:`METH_O`
+   flag, instead of invoking :c:func:`PyArg_ParseTuple` with a ``"O"`` argument.
+   They have the type :c:type:`PyCFunction`, with the *self* parameter, and a
+   :c:type:`PyObject\*` parameter representing the single argument.
+
+
+These two constants are not used to indicate the calling convention but the
+binding when use with methods of classes.  These may not be used for functions
+defined for modules.  At most one of these flags may be set for any given
+method.
+
+
+.. data:: METH_CLASS
+
+   .. index:: builtin: classmethod
+
+   The method will be passed the type object as the first parameter rather
+   than an instance of the type.  This is used to create *class methods*,
+   similar to what is created when using the :func:`classmethod` built-in
+   function.
+
+
+.. data:: METH_STATIC
+
+   .. index:: builtin: staticmethod
+
+   The method will be passed *NULL* as the first parameter rather than an
+   instance of the type.  This is used to create *static methods*, similar to
+   what is created when using the :func:`staticmethod` built-in function.
+
+One other constant controls whether a method is loaded in place of another
+definition with the same method name.
+
+
+.. data:: METH_COEXIST
+
+   The method will be loaded in place of existing definitions.  Without
+   *METH_COEXIST*, the default is to skip repeated definitions.  Since slot
+   wrappers are loaded before the method table, the existence of a
+   *sq_contains* slot, for example, would generate a wrapped method named
+   :meth:`__contains__` and preclude the loading of a corresponding
+   PyCFunction with the same name.  With the flag defined, the PyCFunction
+   will be loaded in place of the wrapper object and will co-exist with the
+   slot.  This is helpful because calls to PyCFunctions are optimized more
+   than wrapper object calls.
+
+
+.. c:type:: PyMemberDef
+
+   Structure which describes an attribute of a type which corresponds to a C
+   struct member.  Its fields are:
+
+   +------------------+-------------+-------------------------------+
+   | Field            | C Type      | Meaning                       |
+   +==================+=============+===============================+
+   | :attr:`name`     | char \*     | name of the member            |
+   +------------------+-------------+-------------------------------+
+   | :attr:`!type`    | int         | the type of the member in the |
+   |                  |             | C struct                      |
+   +------------------+-------------+-------------------------------+
+   | :attr:`offset`   | Py_ssize_t  | the offset in bytes that the  |
+   |                  |             | member is located on the      |
+   |                  |             | type's object struct          |
+   +------------------+-------------+-------------------------------+
+   | :attr:`flags`    | int         | flag bits indicating if the   |
+   |                  |             | field should be read-only or  |
+   |                  |             | writable                      |
+   +------------------+-------------+-------------------------------+
+   | :attr:`doc`      | char \*     | points to the contents of the |
+   |                  |             | docstring                     |
+   +------------------+-------------+-------------------------------+
+
+   :attr:`!type` can be one of many ``T_`` macros corresponding to various C
+   types.  When the member is accessed in Python, it will be converted to the
+   equivalent Python type.
+
+   =============== ==================
+   Macro name      C type
+   =============== ==================
+   T_SHORT         short
+   T_INT           int
+   T_LONG          long
+   T_FLOAT         float
+   T_DOUBLE        double
+   T_STRING        char \*
+   T_OBJECT        PyObject \*
+   T_OBJECT_EX     PyObject \*
+   T_CHAR          char
+   T_BYTE          char
+   T_UBYTE         unsigned char
+   T_UINT          unsigned int
+   T_USHORT        unsigned short
+   T_ULONG         unsigned long
+   T_BOOL          char
+   T_LONGLONG      long long
+   T_ULONGLONG     unsigned long long
+   T_PYSSIZET      Py_ssize_t
+   =============== ==================
+
+   :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` differ in that
+   :c:macro:`T_OBJECT` returns ``None`` if the member is *NULL* and
+   :c:macro:`T_OBJECT_EX` raises an :exc:`AttributeError`.  Try to use
+   :c:macro:`T_OBJECT_EX` over :c:macro:`T_OBJECT` because :c:macro:`T_OBJECT_EX`
+   handles use of the :keyword:`del` statement on that attribute more correctly
+   than :c:macro:`T_OBJECT`.
+
+   :attr:`flags` can be ``0`` for write and read access or :c:macro:`READONLY` for
+   read-only access.  Using :c:macro:`T_STRING` for :attr:`type` implies
+   :c:macro:`READONLY`.  :c:macro:`T_STRING` data is interpreted as UTF-8.
+   Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX`
+   members can be deleted.  (They are set to *NULL*).
+
+
+.. c:type:: PyGetSetDef
+
+   Structure to define property-like access for a type. See also description of
+   the :c:member:`PyTypeObject.tp_getset` slot.
+
+   +-------------+------------------+-----------------------------------+
+   | Field       | C Type           | Meaning                           |
+   +=============+==================+===================================+
+   | name        | char \*          | attribute name                    |
+   +-------------+------------------+-----------------------------------+
+   | get         | getter           | C Function to get the attribute   |
+   +-------------+------------------+-----------------------------------+
+   | set         | setter           | optional C function to set or     |
+   |             |                  | delete the attribute, if omitted  |
+   |             |                  | the attribute is readonly         |
+   +-------------+------------------+-----------------------------------+
+   | doc         | char \*          | optional docstring                |
+   +-------------+------------------+-----------------------------------+
+   | closure     | void \*          | optional function pointer,        |
+   |             |                  | providing additional data for     |
+   |             |                  | getter and setter                 |
+   +-------------+------------------+-----------------------------------+
+
+   The ``get`` function takes one :c:type:`PyObject\*` parameter (the
+   instance) and a function pointer (the associated ``closure``)::
+
+      typedef PyObject *(*getter)(PyObject *, void *);
+
+   It should return a new reference on success or *NULL* with a set exception
+   on failure.
+
+   ``set`` functions take two :c:type:`PyObject\*` parameters (the instance and
+   the value to be set) and a function pointer (the associated ``closure``)::
+
+      typedef int (*setter)(PyObject *, PyObject *, void *);
+
+   In case the attribute should be deleted the second parameter is *NULL*.
+   Should return ``0`` on success or ``-1`` with a set exception on failure.

third_party/python/Doc/c-api/sys.rst

@@ -0,0 +1,267 @@
+.. highlightlang:: c
+
+.. _os:
+
+Operating System Utilities
+==========================
+
+.. c:function:: PyObject* PyOS_FSPath(PyObject *path)
+
+   Return the file system representation for *path*. If the object is a
+   :class:`str` or :class:`bytes` object, then its reference count is
+   incremented. If the object implements the :class:`os.PathLike` interface,
+   then :meth:`~os.PathLike.__fspath__` is returned as long as it is a
+   :class:`str` or :class:`bytes` object. Otherwise :exc:`TypeError` is raised
+   and ``NULL`` is returned.
+
+   .. versionadded:: 3.6
+
+
+.. c:function:: int Py_FdIsInteractive(FILE *fp, const char *filename)
+
+   Return true (nonzero) if the standard I/O file *fp* with name *filename* is
+   deemed interactive.  This is the case for files for which ``isatty(fileno(fp))``
+   is true.  If the global flag :c:data:`Py_InteractiveFlag` is true, this function
+   also returns true if the *filename* pointer is *NULL* or if the name is equal to
+   one of the strings ``'<stdin>'`` or ``'???'``.
+
+
+.. c:function:: void PyOS_AfterFork()
+
+   Function to update some internal state after a process fork; this should be
+   called in the new process if the Python interpreter will continue to be used.
+   If a new executable is loaded into the new process, this function does not need
+   to be called.
+
+
+.. c:function:: int PyOS_CheckStack()
+
+   Return true when the interpreter runs out of stack space.  This is a reliable
+   check, but is only available when :const:`USE_STACKCHECK` is defined (currently
+   on Windows using the Microsoft Visual C++ compiler).  :const:`USE_STACKCHECK`
+   will be defined automatically; you should never change the definition in your
+   own code.
+
+
+.. c:function:: PyOS_sighandler_t PyOS_getsig(int i)
+
+   Return the current signal handler for signal *i*.  This is a thin wrapper around
+   either :c:func:`sigaction` or :c:func:`signal`.  Do not call those functions
+   directly! :c:type:`PyOS_sighandler_t` is a typedef alias for :c:type:`void
+   (\*)(int)`.
+
+
+.. c:function:: PyOS_sighandler_t PyOS_setsig(int i, PyOS_sighandler_t h)
+
+   Set the signal handler for signal *i* to be *h*; return the old signal handler.
+   This is a thin wrapper around either :c:func:`sigaction` or :c:func:`signal`.  Do
+   not call those functions directly!  :c:type:`PyOS_sighandler_t` is a typedef
+   alias for :c:type:`void (\*)(int)`.
+
+.. c:function:: wchar_t* Py_DecodeLocale(const char* arg, size_t *size)
+
+   Decode a byte string from the locale encoding with the :ref:`surrogateescape
+   error handler <surrogateescape>`: undecodable bytes are decoded as
+   characters in range U+DC80..U+DCFF. If a byte sequence can be decoded as a
+   surrogate character, escape the bytes using the surrogateescape error
+   handler instead of decoding them.
+
+   Encoding, highest priority to lowest priority:
+
+   * ``UTF-8`` on macOS and Android;
+   * ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``,
+     ``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias),
+     and :c:func:`mbstowcs` and :c:func:`wcstombs` functions use the
+     ``ISO-8859-1`` encoding.
+   * the current locale encoding (``LC_CTYPE`` locale).
+
+   Return a pointer to a newly allocated wide character string, use
+   :c:func:`PyMem_RawFree` to free the memory. If size is not ``NULL``, write
+   the number of wide characters excluding the null character into ``*size``.
+
+   Return ``NULL`` on decoding error or memory allocation error. If *size* is
+   not ``NULL``, ``*size`` is set to ``(size_t)-1`` on memory error or set to
+   ``(size_t)-2`` on decoding error.
+
+   Decoding errors should never happen, unless there is a bug in the C
+   library.
+
+   Use the :c:func:`Py_EncodeLocale` function to encode the character string
+   back to a byte string.
+
+   .. seealso::
+
+      The :c:func:`PyUnicode_DecodeFSDefaultAndSize` and
+      :c:func:`PyUnicode_DecodeLocaleAndSize` functions.
+
+   .. versionadded:: 3.5
+
+
+.. c:function:: char* Py_EncodeLocale(const wchar_t *text, size_t *error_pos)
+
+   Encode a wide character string to the locale encoding with the
+   :ref:`surrogateescape error handler <surrogateescape>`: surrogate characters
+   in the range U+DC80..U+DCFF are converted to bytes 0x80..0xFF.
+
+   Encoding, highest priority to lowest priority:
+
+   * ``UTF-8`` on macOS and Android;
+   * ``ASCII`` if the ``LC_CTYPE`` locale is ``"C"``,
+     ``nl_langinfo(CODESET)`` returns the ``ASCII`` encoding (or an alias),
+     and :c:func:`mbstowcs` and :c:func:`wcstombs` functions uses the
+     ``ISO-8859-1`` encoding.
+   * the current locale encoding.
+
+   Return a pointer to a newly allocated byte string, use :c:func:`PyMem_Free`
+   to free the memory. Return ``NULL`` on encoding error or memory allocation
+   error
+
+   If error_pos is not ``NULL``, ``*error_pos`` is set to the index of the
+   invalid character on encoding error, or set to ``(size_t)-1`` otherwise.
+
+   Use the :c:func:`Py_DecodeLocale` function to decode the bytes string back
+   to a wide character string.
+
+   .. seealso::
+
+      The :c:func:`PyUnicode_EncodeFSDefault` and
+      :c:func:`PyUnicode_EncodeLocale` functions.
+
+   .. versionadded:: 3.5
+
+
+.. _systemfunctions:
+
+System Functions
+================
+
+These are utility functions that make functionality from the :mod:`sys` module
+accessible to C code.  They all work with the current interpreter thread's
+:mod:`sys` module's dict, which is contained in the internal thread state structure.
+
+.. c:function:: PyObject *PySys_GetObject(const char *name)
+
+   Return the object *name* from the :mod:`sys` module or *NULL* if it does
+   not exist, without setting an exception.
+
+.. c:function:: int PySys_SetObject(const char *name, PyObject *v)
+
+   Set *name* in the :mod:`sys` module to *v* unless *v* is *NULL*, in which
+   case *name* is deleted from the sys module. Returns ``0`` on success, ``-1``
+   on error.
+
+.. c:function:: void PySys_ResetWarnOptions()
+
+   Reset :data:`sys.warnoptions` to an empty list.
+
+.. c:function:: void PySys_AddWarnOption(wchar_t *s)
+
+   Append *s* to :data:`sys.warnoptions`.
+
+.. c:function:: void PySys_AddWarnOptionUnicode(PyObject *unicode)
+
+   Append *unicode* to :data:`sys.warnoptions`.
+
+.. c:function:: void PySys_SetPath(wchar_t *path)
+
+   Set :data:`sys.path` to a list object of paths found in *path* which should
+   be a list of paths separated with the platform's search path delimiter
+   (``:`` on Unix, ``;`` on Windows).
+
+.. c:function:: void PySys_WriteStdout(const char *format, ...)
+
+   Write the output string described by *format* to :data:`sys.stdout`.  No
+   exceptions are raised, even if truncation occurs (see below).
+
+   *format* should limit the total size of the formatted output string to
+   1000 bytes or less -- after 1000 bytes, the output string is truncated.
+   In particular, this means that no unrestricted "%s" formats should occur;
+   these should be limited using "%.<N>s" where <N> is a decimal number
+   calculated so that <N> plus the maximum size of other formatted text does not
+   exceed 1000 bytes.  Also watch out for "%f", which can print hundreds of
+   digits for very large numbers.
+
+   If a problem occurs, or :data:`sys.stdout` is unset, the formatted message
+   is written to the real (C level) *stdout*.
+
+.. c:function:: void PySys_WriteStderr(const char *format, ...)
+
+   As :c:func:`PySys_WriteStdout`, but write to :data:`sys.stderr` or *stderr*
+   instead.
+
+.. c:function:: void PySys_FormatStdout(const char *format, ...)
+
+   Function similar to PySys_WriteStdout() but format the message using
+   :c:func:`PyUnicode_FromFormatV` and don't truncate the message to an
+   arbitrary length.
+
+   .. versionadded:: 3.2
+
+.. c:function:: void PySys_FormatStderr(const char *format, ...)
+
+   As :c:func:`PySys_FormatStdout`, but write to :data:`sys.stderr` or *stderr*
+   instead.
+
+   .. versionadded:: 3.2
+
+.. c:function:: void PySys_AddXOption(const wchar_t *s)
+
+   Parse *s* as a set of :option:`-X` options and add them to the current
+   options mapping as returned by :c:func:`PySys_GetXOptions`.
+
+   .. versionadded:: 3.2
+
+.. c:function:: PyObject *PySys_GetXOptions()
+
+   Return the current dictionary of :option:`-X` options, similarly to
+   :data:`sys._xoptions`.  On error, *NULL* is returned and an exception is
+   set.
+
+   .. versionadded:: 3.2
+
+
+.. _processcontrol:
+
+Process Control
+===============
+
+
+.. c:function:: void Py_FatalError(const char *message)
+
+   .. index:: single: abort()
+
+   Print a fatal error message and kill the process.  No cleanup is performed.
+   This function should only be invoked when a condition is detected that would
+   make it dangerous to continue using the Python interpreter; e.g., when the
+   object administration appears to be corrupted.  On Unix, the standard C library
+   function :c:func:`abort` is called which will attempt to produce a :file:`core`
+   file.
+
+
+.. c:function:: void Py_Exit(int status)
+
+   .. index::
+      single: Py_FinalizeEx()
+      single: exit()
+
+   Exit the current process.  This calls :c:func:`Py_FinalizeEx` and then calls the
+   standard C library function ``exit(status)``.  If :c:func:`Py_FinalizeEx`
+   indicates an error, the exit status is set to 120.
+
+   .. versionchanged:: 3.6
+      Errors from finalization no longer ignored.
+
+
+.. c:function:: int Py_AtExit(void (*func) ())
+
+   .. index::
+      single: Py_FinalizeEx()
+      single: cleanup functions
+
+   Register a cleanup function to be called by :c:func:`Py_FinalizeEx`.  The cleanup
+   function will be called with no arguments and should return no value.  At most
+   32 cleanup functions can be registered.  When the registration is successful,
+   :c:func:`Py_AtExit` returns ``0``; on failure, it returns ``-1``.  The cleanup
+   function registered last is called first. Each cleanup function will be called
+   at most once.  Since Python's internal finalization will have completed before
+   the cleanup function, no Python APIs should be called by *func*.

third_party/python/Doc/c-api/tuple.rst

@@ -0,0 +1,218 @@
+.. highlightlang:: c
+
+.. _tupleobjects:
+
+Tuple Objects
+-------------
+
+.. index:: object: tuple
+
+
+.. c:type:: PyTupleObject
+
+   This subtype of :c:type:`PyObject` represents a Python tuple object.
+
+
+.. c:var:: PyTypeObject PyTuple_Type
+
+   This instance of :c:type:`PyTypeObject` represents the Python tuple type; it
+   is the same object as :class:`tuple` in the Python layer.
+
+
+.. c:function:: int PyTuple_Check(PyObject *p)
+
+   Return true if *p* is a tuple object or an instance of a subtype of the tuple
+   type.
+
+
+.. c:function:: int PyTuple_CheckExact(PyObject *p)
+
+   Return true if *p* is a tuple object, but not an instance of a subtype of the
+   tuple type.
+
+
+.. c:function:: PyObject* PyTuple_New(Py_ssize_t len)
+
+   Return a new tuple object of size *len*, or *NULL* on failure.
+
+
+.. c:function:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
+
+   Return a new tuple object of size *n*, or *NULL* on failure. The tuple values
+   are initialized to the subsequent *n* C arguments pointing to Python objects.
+   ``PyTuple_Pack(2, a, b)`` is equivalent to ``Py_BuildValue("(OO)", a, b)``.
+
+
+.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p)
+
+   Take a pointer to a tuple object, and return the size of that tuple.
+
+
+.. c:function:: Py_ssize_t PyTuple_GET_SIZE(PyObject *p)
+
+   Return the size of the tuple *p*, which must be non-*NULL* and point to a tuple;
+   no error checking is performed.
+
+
+.. c:function:: PyObject* PyTuple_GetItem(PyObject *p, Py_ssize_t pos)
+
+   Return the object at position *pos* in the tuple pointed to by *p*.  If *pos* is
+   out of bounds, return *NULL* and sets an :exc:`IndexError` exception.
+
+
+.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
+
+   Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments.
+
+
+.. c:function:: PyObject* PyTuple_GetSlice(PyObject *p, Py_ssize_t low, Py_ssize_t high)
+
+   Take a slice of the tuple pointed to by *p* from *low* to *high* and return it
+   as a new tuple.
+
+
+.. c:function:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+   Insert a reference to object *o* at position *pos* of the tuple pointed to by
+   *p*. Return ``0`` on success.
+
+   .. note::
+
+      This function "steals" a reference to *o*.
+
+
+.. c:function:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+   Like :c:func:`PyTuple_SetItem`, but does no error checking, and should *only* be
+   used to fill in brand new tuples.
+
+   .. note::
+
+      This function "steals" a reference to *o*.
+
+
+.. c:function:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
+
+   Can be used to resize a tuple.  *newsize* will be the new length of the tuple.
+   Because tuples are *supposed* to be immutable, this should only be used if there
+   is only one reference to the object.  Do *not* use this if the tuple may already
+   be known to some other part of the code.  The tuple will always grow or shrink
+   at the end.  Think of this as destroying the old tuple and creating a new one,
+   only more efficiently.  Returns ``0`` on success. Client code should never
+   assume that the resulting value of ``*p`` will be the same as before calling
+   this function. If the object referenced by ``*p`` is replaced, the original
+   ``*p`` is destroyed.  On failure, returns ``-1`` and sets ``*p`` to *NULL*, and
+   raises :exc:`MemoryError` or :exc:`SystemError`.
+
+
+.. c:function:: int PyTuple_ClearFreeList()
+
+   Clear the free list. Return the total number of freed items.
+
+
+Struct Sequence Objects
+-----------------------
+
+Struct sequence objects are the C equivalent of :func:`~collections.namedtuple`
+objects, i.e. a sequence whose items can also be accessed through attributes.
+To create a struct sequence, you first have to create a specific struct sequence
+type.
+
+.. c:function:: PyTypeObject* PyStructSequence_NewType(PyStructSequence_Desc *desc)
+
+   Create a new struct sequence type from the data in *desc*, described below. Instances
+   of the resulting type can be created with :c:func:`PyStructSequence_New`.
+
+
+.. c:function:: void PyStructSequence_InitType(PyTypeObject *type, PyStructSequence_Desc *desc)
+
+   Initializes a struct sequence type *type* from *desc* in place.
+
+
+.. c:function:: int PyStructSequence_InitType2(PyTypeObject *type, PyStructSequence_Desc *desc)
+
+   The same as ``PyStructSequence_InitType``, but returns ``0`` on success and ``-1`` on
+   failure.
+
+   .. versionadded:: 3.4
+
+
+.. c:type:: PyStructSequence_Desc
+
+   Contains the meta information of a struct sequence type to create.
+
+   +-------------------+------------------------------+------------------------------------+
+   | Field             | C Type                       | Meaning                            |
+   +===================+==============================+====================================+
+   | ``name``          | ``char *``                   | name of the struct sequence type   |
+   +-------------------+------------------------------+------------------------------------+
+   | ``doc``           | ``char *``                   | pointer to docstring for the type  |
+   |                   |                              | or NULL to omit                    |
+   +-------------------+------------------------------+------------------------------------+
+   | ``fields``        | ``PyStructSequence_Field *`` | pointer to *NULL*-terminated array |
+   |                   |                              | with field names of the new type   |
+   +-------------------+------------------------------+------------------------------------+
+   | ``n_in_sequence`` | ``int``                      | number of fields visible to the    |
+   |                   |                              | Python side (if used as tuple)     |
+   +-------------------+------------------------------+------------------------------------+
+
+
+.. c:type:: PyStructSequence_Field
+
+   Describes a field of a struct sequence. As a struct sequence is modeled as a
+   tuple, all fields are typed as :c:type:`PyObject\*`.  The index in the
+   :attr:`fields` array of the :c:type:`PyStructSequence_Desc` determines which
+   field of the struct sequence is described.
+
+   +-----------+---------------+--------------------------------------+
+   | Field     | C Type        | Meaning                              |
+   +===========+===============+======================================+
+   | ``name``  | ``char *``    | name for the field or *NULL* to end  |
+   |           |               | the list of named fields, set to     |
+   |           |               | PyStructSequence_UnnamedField to     |
+   |           |               | leave unnamed                        |
+   +-----------+---------------+--------------------------------------+
+   | ``doc``   | ``char *``    | field docstring or *NULL* to omit    |
+   +-----------+---------------+--------------------------------------+
+
+
+.. c:var:: char* PyStructSequence_UnnamedField
+
+   Special value for a field name to leave it unnamed.
+
+
+.. c:function:: PyObject* PyStructSequence_New(PyTypeObject *type)
+
+   Creates an instance of *type*, which must have been created with
+   :c:func:`PyStructSequence_NewType`.
+
+
+.. c:function:: PyObject* PyStructSequence_GetItem(PyObject *p, Py_ssize_t pos)
+
+   Return the object at position *pos* in the struct sequence pointed to by *p*.
+   No bounds checking is performed.
+
+
+.. c:function:: PyObject* PyStructSequence_GET_ITEM(PyObject *p, Py_ssize_t pos)
+
+   Macro equivalent of :c:func:`PyStructSequence_GetItem`.
+
+
+.. c:function:: void PyStructSequence_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
+
+   Sets the field at index *pos* of the struct sequence *p* to value *o*.  Like
+   :c:func:`PyTuple_SET_ITEM`, this should only be used to fill in brand new
+   instances.
+
+   .. note::
+
+      This function "steals" a reference to *o*.
+
+
+.. c:function:: void PyStructSequence_SET_ITEM(PyObject *p, Py_ssize_t *pos, PyObject *o)
+
+   Macro equivalent of :c:func:`PyStructSequence_SetItem`.
+
+   .. note::
+
+      This function "steals" a reference to *o*.

third_party/python/Doc/c-api/type.rst

@@ -0,0 +1,118 @@
+.. highlightlang:: c
+
+.. _typeobjects:
+
+Type Objects
+------------
+
+.. index:: object: type
+
+
+.. c:type:: PyTypeObject
+
+   The C structure of the objects used to describe built-in types.
+
+
+.. c:var:: PyObject* PyType_Type
+
+   This is the type object for type objects; it is the same object as
+   :class:`type` in the Python layer.
+
+
+.. c:function:: int PyType_Check(PyObject *o)
+
+   Return true if the object *o* is a type object, including instances of types
+   derived from the standard type object.  Return false in all other cases.
+
+
+.. c:function:: int PyType_CheckExact(PyObject *o)
+
+   Return true if the object *o* is a type object, but not a subtype of the
+   standard type object.  Return false in all other cases.
+
+
+.. c:function:: unsigned int PyType_ClearCache()
+
+   Clear the internal lookup cache. Return the current version tag.
+
+.. c:function:: unsigned long PyType_GetFlags(PyTypeObject* type)
+
+   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
+   :c:member:`~PyTypeObject.tp_flags` itself is not part of the limited API.
+
+   .. versionadded:: 3.2
+
+   .. versionchanged:: 3.4
+      The return type is now ``unsigned long`` rather than ``long``.
+
+
+.. c:function:: void PyType_Modified(PyTypeObject *type)
+
+   Invalidate the internal lookup cache for the type and all of its
+   subtypes.  This function must be called after any manual
+   modification of the attributes or base classes of the type.
+
+
+.. c:function:: int PyType_HasFeature(PyTypeObject *o, int feature)
+
+   Return true if the type object *o* sets the feature *feature*.  Type features
+   are denoted by single bit flags.
+
+
+.. c:function:: int PyType_IS_GC(PyTypeObject *o)
+
+   Return true if the type object includes support for the cycle detector; this
+   tests the type flag :const:`Py_TPFLAGS_HAVE_GC`.
+
+
+.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b)
+
+   Return true if *a* is a subtype of *b*.
+
+   This function only checks for actual subtypes, which means that
+   :meth:`~class.__subclasscheck__` is not called on *b*.  Call
+   :c:func:`PyObject_IsSubclass` to do the same check that :func:`issubclass`
+   would do.
+
+
+.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems)
+
+   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 :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)
+
+   Finalize a type object.  This should be called on all type objects to finish
+   their initialization.  This function is responsible for adding inherited slots
+   from a type's base class.  Return ``0`` on success, or return ``-1`` and sets an
+   exception on error.
+
+.. c:function:: PyObject* PyType_FromSpec(PyType_Spec *spec)
+
+   Creates and returns a heap type object from the *spec* passed to the function.
+
+.. c:function:: PyObject* PyType_FromSpecWithBases(PyType_Spec *spec, PyObject *bases)
+
+   Creates and returns a heap type object from the *spec*. In addition to that,
+   the created heap type contains all types contained by the *bases* tuple as base
+   types. This allows the caller to reference other heap types as base types.
+
+   .. versionadded:: 3.3
+
+.. c:function:: void* PyType_GetSlot(PyTypeObject *type, int slot)
+
+   Return the function pointer stored in the given slot. If the
+   result is *NULL*, this indicates that either the slot is *NULL*,
+   or that the function was called with invalid parameters.
+   Callers will typically cast the result pointer into the appropriate
+   function type.
+
+   .. versionadded:: 3.4

third_party/python/Doc/c-api/utilities.rst

@@ -0,0 +1,21 @@
+.. highlightlang:: c
+
+.. _utilities:
+
+*********
+Utilities
+*********
+
+The functions in this chapter perform various utility tasks, ranging from
+helping C code be more portable across platforms, using Python modules from C,
+and parsing function arguments and constructing Python values from C values.
+
+.. toctree::
+
+   sys.rst
+   import.rst
+   marshal.rst
+   arg.rst
+   conversion.rst
+   reflection.rst
+   codec.rst

third_party/python/Doc/c-api/veryhigh.rst

@@ -0,0 +1,390 @@
+.. highlightlang:: c
+
+
+.. _veryhigh:
+
+*************************
+The Very High Level Layer
+*************************
+
+The functions in this chapter will let you execute Python source code given in a
+file or a buffer, but they will not let you interact in a more detailed way with
+the interpreter.
+
+Several of these functions accept a start symbol from the grammar as a
+parameter.  The available start symbols are :const:`Py_eval_input`,
+:const:`Py_file_input`, and :const:`Py_single_input`.  These are described
+following the functions which accept them as parameters.
+
+Note also that several of these functions take :c:type:`FILE\*` parameters.  One
+particular issue which needs to be handled carefully is that the :c:type:`FILE`
+structure for different C libraries can be different and incompatible.  Under
+Windows (at least), it is possible for dynamically linked extensions to actually
+use different libraries, so care should be taken that :c:type:`FILE\*` parameters
+are only passed to these functions if it is certain that they were created by
+the same library that the Python runtime is using.
+
+
+.. c:function:: int Py_Main(int argc, wchar_t **argv)
+
+   The main program for the standard interpreter.  This is made available for
+   programs which embed Python.  The *argc* and *argv* parameters should be
+   prepared exactly as those which are passed to a C program's :c:func:`main`
+   function (converted to wchar_t according to the user's locale).  It is
+   important to note that the argument list may be modified (but the contents of
+   the strings pointed to by the argument list are not). The return value will
+   be ``0`` if the interpreter exits normally (i.e., without an exception),
+   ``1`` if the interpreter exits due to an exception, or ``2`` if the parameter
+   list does not represent a valid Python command line.
+
+   Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
+   function will not return ``1``, but exit the process, as long as
+   ``Py_InspectFlag`` is not set.
+
+
+.. c:function:: int PyRun_AnyFile(FILE *fp, const char *filename)
+
+   This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
+   *closeit* set to ``0`` and *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_AnyFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+   This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
+   the *closeit* argument set to ``0``.
+
+
+.. c:function:: int PyRun_AnyFileEx(FILE *fp, const char *filename, int closeit)
+
+   This is a simplified interface to :c:func:`PyRun_AnyFileExFlags` below, leaving
+   the *flags* argument set to *NULL*.
+
+
+.. c:function:: int PyRun_AnyFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
+
+   If *fp* refers to a file associated with an interactive device (console or
+   terminal input or Unix pseudo-terminal), return the value of
+   :c:func:`PyRun_InteractiveLoop`, otherwise return the result of
+   :c:func:`PyRun_SimpleFile`.  *filename* is decoded from the filesystem
+   encoding (:func:`sys.getfilesystemencoding`).  If *filename* is *NULL*, this
+   function uses ``"???"`` as the filename.
+
+
+.. c:function:: int PyRun_SimpleString(const char *command)
+
+   This is a simplified interface to :c:func:`PyRun_SimpleStringFlags` below,
+   leaving the *PyCompilerFlags\** argument set to NULL.
+
+
+.. c:function:: int PyRun_SimpleStringFlags(const char *command, PyCompilerFlags *flags)
+
+   Executes the Python source code from *command* in the :mod:`__main__` module
+   according to the *flags* argument. If :mod:`__main__` does not already exist, it
+   is created.  Returns ``0`` on success or ``-1`` if an exception was raised.  If
+   there was an error, there is no way to get the exception information. For the
+   meaning of *flags*, see below.
+
+   Note that if an otherwise unhandled :exc:`SystemExit` is raised, this
+   function will not return ``-1``, but exit the process, as long as
+   ``Py_InspectFlag`` is not set.
+
+
+.. c:function:: int PyRun_SimpleFile(FILE *fp, const char *filename)
+
+   This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
+   leaving *closeit* set to ``0`` and *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_SimpleFileEx(FILE *fp, const char *filename, int closeit)
+
+   This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below,
+   leaving *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_SimpleFileExFlags(FILE *fp, const char *filename, int closeit, PyCompilerFlags *flags)
+
+   Similar to :c:func:`PyRun_SimpleStringFlags`, but the Python source code is read
+   from *fp* instead of an in-memory string. *filename* should be the name of
+   the file, it is decoded from the filesystem encoding
+   (:func:`sys.getfilesystemencoding`).  If *closeit* is true, the file is
+   closed before PyRun_SimpleFileExFlags returns.
+
+
+.. c:function:: int PyRun_InteractiveOne(FILE *fp, const char *filename)
+
+   This is a simplified interface to :c:func:`PyRun_InteractiveOneFlags` below,
+   leaving *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_InteractiveOneFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+   Read and execute a single statement from a file associated with an
+   interactive device according to the *flags* argument.  The user will be
+   prompted using ``sys.ps1`` and ``sys.ps2``.  *filename* is decoded from the
+   filesystem encoding (:func:`sys.getfilesystemencoding`).
+
+   Returns ``0`` when the input was
+   executed successfully, ``-1`` if there was an exception, or an error code
+   from the :file:`errcode.h` include file distributed as part of Python if
+   there was a parse error.  (Note that :file:`errcode.h` is not included by
+   :file:`Python.h`, so must be included specifically if needed.)
+
+
+.. c:function:: int PyRun_InteractiveLoop(FILE *fp, const char *filename)
+
+   This is a simplified interface to :c:func:`PyRun_InteractiveLoopFlags` below,
+   leaving *flags* set to *NULL*.
+
+
+.. c:function:: int PyRun_InteractiveLoopFlags(FILE *fp, const char *filename, PyCompilerFlags *flags)
+
+   Read and execute statements from a file associated with an interactive device
+   until EOF is reached.  The user will be prompted using ``sys.ps1`` and
+   ``sys.ps2``.  *filename* is decoded from the filesystem encoding
+   (:func:`sys.getfilesystemencoding`).  Returns ``0`` at EOF or a negative
+   number upon failure.
+
+
+.. c:var:: int (*PyOS_InputHook)(void)
+
+   Can be set to point to a function with the prototype
+   ``int func(void)``.  The function will be called when Python's
+   interpreter prompt is about to become idle and wait for user input
+   from the terminal.  The return value is ignored.  Overriding this
+   hook can be used to integrate the interpreter's prompt with other
+   event loops, as done in the :file:`Modules/_tkinter.c` in the
+   Python source code.
+
+
+.. c:var:: char* (*PyOS_ReadlineFunctionPointer)(FILE *, FILE *, const char *)
+
+   Can be set to point to a function with the prototype
+   ``char *func(FILE *stdin, FILE *stdout, char *prompt)``,
+   overriding the default function used to read a single line of input
+   at the interpreter's prompt.  The function is expected to output
+   the string *prompt* if it's not *NULL*, and then read a line of
+   input from the provided standard input file, returning the
+   resulting string.  For example, The :mod:`readline` module sets
+   this hook to provide line-editing and tab-completion features.
+
+   The result must be a string allocated by :c:func:`PyMem_RawMalloc` or
+   :c:func:`PyMem_RawRealloc`, or *NULL* if an error occurred.
+
+   .. versionchanged:: 3.4
+      The result must be allocated by :c:func:`PyMem_RawMalloc` or
+      :c:func:`PyMem_RawRealloc`, instead of being allocated by
+      :c:func:`PyMem_Malloc` or :c:func:`PyMem_Realloc`.
+
+
+.. c:function:: struct _node* PyParser_SimpleParseString(const char *str, int start)
+
+   This is a simplified interface to
+   :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set
+   to *NULL* and *flags* set to ``0``.
+
+
+.. c:function:: struct _node* PyParser_SimpleParseStringFlags( const char *str, int start, int flags)
+
+   This is a simplified interface to
+   :c:func:`PyParser_SimpleParseStringFlagsFilename` below, leaving  *filename* set
+   to *NULL*.
+
+
+.. c:function:: struct _node* PyParser_SimpleParseStringFlagsFilename( const char *str, const char *filename, int start, int flags)
+
+   Parse Python source code from *str* using the start token *start* according to
+   the *flags* argument.  The result can be used to create a code object which can
+   be evaluated efficiently. This is useful if a code fragment must be evaluated
+   many times. *filename* is decoded from the filesystem encoding
+   (:func:`sys.getfilesystemencoding`).
+
+
+.. c:function:: struct _node* PyParser_SimpleParseFile(FILE *fp, const char *filename, int start)
+
+   This is a simplified interface to :c:func:`PyParser_SimpleParseFileFlags` below,
+   leaving *flags* set to ``0``.
+
+
+.. c:function:: struct _node* PyParser_SimpleParseFileFlags(FILE *fp, const char *filename, int start, int flags)
+
+   Similar to :c:func:`PyParser_SimpleParseStringFlagsFilename`, but the Python
+   source code is read from *fp* instead of an in-memory string.
+
+
+.. c:function:: PyObject* PyRun_String(const char *str, int start, PyObject *globals, PyObject *locals)
+
+   This is a simplified interface to :c:func:`PyRun_StringFlags` below, leaving
+   *flags* set to *NULL*.
+
+
+.. c:function:: PyObject* PyRun_StringFlags(const char *str, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
+
+   Execute Python source code from *str* in the context specified by the
+   objects *globals* and *locals* with the compiler flags specified by
+   *flags*.  *globals* must be a dictionary; *locals* can be any object
+   that implements the mapping protocol.  The parameter *start* specifies
+   the start token that should be used to parse the source code.
+
+   Returns the result of executing the code as a Python object, or *NULL* if an
+   exception was raised.
+
+
+.. c:function:: PyObject* PyRun_File(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals)
+
+   This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
+   *closeit* set to ``0`` and *flags* set to *NULL*.
+
+
+.. c:function:: PyObject* PyRun_FileEx(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit)
+
+   This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
+   *flags* set to *NULL*.
+
+
+.. c:function:: PyObject* PyRun_FileFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, PyCompilerFlags *flags)
+
+   This is a simplified interface to :c:func:`PyRun_FileExFlags` below, leaving
+   *closeit* set to ``0``.
+
+
+.. c:function:: PyObject* PyRun_FileExFlags(FILE *fp, const char *filename, int start, PyObject *globals, PyObject *locals, int closeit, PyCompilerFlags *flags)
+
+   Similar to :c:func:`PyRun_StringFlags`, but the Python source code is read from
+   *fp* instead of an in-memory string. *filename* should be the name of the file,
+   it is decoded from the filesystem encoding (:func:`sys.getfilesystemencoding`).
+   If *closeit* is true, the file is closed before :c:func:`PyRun_FileExFlags`
+   returns.
+
+
+.. c:function:: PyObject* Py_CompileString(const char *str, const char *filename, int start)
+
+   This is a simplified interface to :c:func:`Py_CompileStringFlags` below, leaving
+   *flags* set to *NULL*.
+
+
+.. c:function:: PyObject* Py_CompileStringFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags)
+
+   This is a simplified interface to :c:func:`Py_CompileStringExFlags` below, with
+   *optimize* set to ``-1``.
+
+
+.. c:function:: PyObject* Py_CompileStringObject(const char *str, PyObject *filename, int start, PyCompilerFlags *flags, int optimize)
+
+   Parse and compile the Python source code in *str*, returning the resulting code
+   object.  The start token is given by *start*; this can be used to constrain the
+   code which can be compiled and should be :const:`Py_eval_input`,
+   :const:`Py_file_input`, or :const:`Py_single_input`.  The filename specified by
+   *filename* is used to construct the code object and may appear in tracebacks or
+   :exc:`SyntaxError` exception messages.  This returns *NULL* if the code
+   cannot be parsed or compiled.
+
+   The integer *optimize* specifies the optimization level of the compiler; a
+   value of ``-1`` selects the optimization level of the interpreter as given by
+   :option:`-O` options.  Explicit levels are ``0`` (no optimization;
+   ``__debug__`` is true), ``1`` (asserts are removed, ``__debug__`` is false)
+   or ``2`` (docstrings are removed too).
+
+   .. versionadded:: 3.4
+
+
+.. c:function:: PyObject* Py_CompileStringExFlags(const char *str, const char *filename, int start, PyCompilerFlags *flags, int optimize)
+
+   Like :c:func:`Py_CompileStringObject`, but *filename* is a byte string
+   decoded from the filesystem encoding (:func:`os.fsdecode`).
+
+   .. versionadded:: 3.2
+
+.. c:function:: PyObject* PyEval_EvalCode(PyObject *co, PyObject *globals, PyObject *locals)
+
+   This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just
+   the code object, and global and local variables.  The other arguments are
+   set to *NULL*.
+
+
+.. c:function:: PyObject* PyEval_EvalCodeEx(PyObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *kwdefs, PyObject *closure)
+
+   Evaluate a precompiled code object, given a particular environment for its
+   evaluation.  This environment consists of a dictionary of global variables,
+   a mapping object of local variables, arrays of arguments, keywords and
+   defaults, a dictionary of default values for :ref:`keyword-only
+   <keyword-only_parameter>` arguments and a closure tuple of cells.
+
+
+.. c:type:: PyFrameObject
+
+   The C structure of the objects used to describe frame objects. The
+   fields of this type are subject to change at any time.
+
+
+.. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
+
+   Evaluate an execution frame.  This is a simplified interface to
+   :c:func:`PyEval_EvalFrameEx`, for backward compatibility.
+
+
+.. c:function:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
+
+   This is the main, unvarnished function of Python interpretation.  It is
+   literally 2000 lines long.  The code object associated with the execution
+   frame *f* is executed, interpreting bytecode and executing calls as needed.
+   The additional *throwflag* parameter can mostly be ignored - if true, then
+   it causes an exception to immediately be thrown; this is used for the
+   :meth:`~generator.throw` methods of generator objects.
+
+   .. versionchanged:: 3.4
+      This function now includes a debug assertion to help ensure that it
+      does not silently discard an active exception.
+
+
+.. c:function:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
+
+   This function changes the flags of the current evaluation frame, and returns
+   true on success, false on failure.
+
+
+.. c:var:: int Py_eval_input
+
+   .. index:: single: Py_CompileString()
+
+   The start symbol from the Python grammar for isolated expressions; for use with
+   :c:func:`Py_CompileString`.
+
+
+.. c:var:: int Py_file_input
+
+   .. index:: single: Py_CompileString()
+
+   The start symbol from the Python grammar for sequences of statements as read
+   from a file or other source; for use with :c:func:`Py_CompileString`.  This is
+   the symbol to use when compiling arbitrarily long Python source code.
+
+
+.. c:var:: int Py_single_input
+
+   .. index:: single: Py_CompileString()
+
+   The start symbol from the Python grammar for a single statement; for use with
+   :c:func:`Py_CompileString`. This is the symbol used for the interactive
+   interpreter loop.
+
+
+.. c:type:: struct PyCompilerFlags
+
+   This is the structure used to hold compiler flags.  In cases where code is only
+   being compiled, it is passed as ``int flags``, and in cases where code is being
+   executed, it is passed as ``PyCompilerFlags *flags``.  In this case, ``from
+   __future__ import`` can modify *flags*.
+
+   Whenever ``PyCompilerFlags *flags`` is *NULL*, :attr:`cf_flags` is treated as
+   equal to ``0``, and any modification due to ``from __future__ import`` is
+   discarded.  ::
+
+      struct PyCompilerFlags {
+          int cf_flags;
+      }
+
+
+.. c:var:: int CO_FUTURE_DIVISION
+
+   This bit can be set in *flags* to cause division operator ``/`` to be
+   interpreted as "true division" according to :pep:`238`.

third_party/python/Doc/c-api/weakref.rst

@@ -0,0 +1,69 @@
+.. highlightlang:: c
+
+.. _weakrefobjects:
+
+Weak Reference Objects
+----------------------
+
+Python supports *weak references* as first-class objects.  There are two
+specific object types which directly implement weak references.  The first is a
+simple reference object, and the second acts as a proxy for the original object
+as much as it can.
+
+
+.. c:function:: int PyWeakref_Check(ob)
+
+   Return true if *ob* is either a reference or proxy object.
+
+
+.. c:function:: int PyWeakref_CheckRef(ob)
+
+   Return true if *ob* is a reference object.
+
+
+.. c:function:: int PyWeakref_CheckProxy(ob)
+
+   Return true if *ob* is a proxy object.
+
+
+.. c:function:: PyObject* PyWeakref_NewRef(PyObject *ob, PyObject *callback)
+
+   Return a weak reference object for the object *ob*.  This will always return
+   a new reference, but is not guaranteed to create a new object; an existing
+   reference object may be returned.  The second parameter, *callback*, can be a
+   callable object that receives notification when *ob* is garbage collected; it
+   should accept a single parameter, which will be the weak reference object
+   itself. *callback* may also be ``None`` or *NULL*.  If *ob* is not a
+   weakly-referencable object, or if *callback* is not callable, ``None``, or
+   *NULL*, this will return *NULL* and raise :exc:`TypeError`.
+
+
+.. c:function:: PyObject* PyWeakref_NewProxy(PyObject *ob, PyObject *callback)
+
+   Return a weak reference proxy object for the object *ob*.  This will always
+   return a new reference, but is not guaranteed to create a new object; an
+   existing proxy object may be returned.  The second parameter, *callback*, can
+   be a callable object that receives notification when *ob* is garbage
+   collected; it should accept a single parameter, which will be the weak
+   reference object itself. *callback* may also be ``None`` or *NULL*.  If *ob*
+   is not a weakly-referencable object, or if *callback* is not callable,
+   ``None``, or *NULL*, this will return *NULL* and raise :exc:`TypeError`.
+
+
+.. c:function:: PyObject* PyWeakref_GetObject(PyObject *ref)
+
+   Return the referenced object from a weak reference, *ref*.  If the referent is
+   no longer live, returns :const:`Py_None`.
+
+   .. note::
+
+      This function returns a **borrowed reference** to the referenced object.
+      This means that you should always call :c:func:`Py_INCREF` on the object
+      except if you know that it cannot be destroyed while you are still
+      using it.
+
+
+.. c:function:: PyObject* PyWeakref_GET_OBJECT(PyObject *ref)
+
+   Similar to :c:func:`PyWeakref_GetObject`, but implemented as a macro that does no
+   error checking.