Added unmodified Python-2.7.5 sources Change-Id: I230169787cb61d59d4b31f81bcdf98b57454c70b
diff --git a/Python-2.7.5/Doc/c-api/abstract.rst b/Python-2.7.5/Doc/c-api/abstract.rst new file mode 100644 index 0000000..bc9001c --- /dev/null +++ b/Python-2.7.5/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 + objbuffer.rst
diff --git a/Python-2.7.5/Doc/c-api/allocation.rst b/Python-2.7.5/Doc/c-api/allocation.rst new file mode 100644 index 0000000..cb43cbf --- /dev/null +++ b/Python-2.7.5/Doc/c-api/allocation.rst
@@ -0,0 +1,122 @@ +.. 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) + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: void _PyObject_Del(PyObject *op) + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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 :attr:`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 :attr:`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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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 + :attr:`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:function:: PyObject* Py_InitModule(char *name, PyMethodDef *methods) + + Create a new module object based on a name and table of functions, + returning the new module object. + + .. versionchanged:: 2.3 + Older versions of Python did not support *NULL* as the value for the + *methods* argument. + + +.. c:function:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc) + + Create a new module object based on a name and table of functions, + returning the new module object. If *doc* is non-*NULL*, it will be used + to define the docstring for the module. + + .. versionchanged:: 2.3 + Older versions of Python did not support *NULL* as the value for the + *methods* argument. + + +.. c:function:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver) + + Create a new module object based on a name and table of functions, + returning the new module object. If *doc* is non-*NULL*, it will be used + to define the docstring for the module. If *self* is non-*NULL*, it will + passed to the functions of the module as their (otherwise *NULL*) first + parameter. (This was added as an experimental feature, and there are no + known uses in the current version of Python.) For *apiver*, the only value + which should be passed is defined by the constant + :const:`PYTHON_API_VERSION`. + + .. note:: + + Most uses of this function should probably be using the + :c:func:`Py_InitModule3` instead; only use this if you are sure you need + it. + + .. versionchanged:: 2.3 + Older versions of Python did not support *NULL* as the value for the + *methods* argument. + + +.. c:var:: PyObject _Py_NoneStruct + + Object which is visible in Python as ``None``. This should only be + accessed using the ``Py_None`` macro, which evaluates to a pointer to this + object.
diff --git a/Python-2.7.5/Doc/c-api/arg.rst b/Python-2.7.5/Doc/c-api/arg.rst new file mode 100644 index 0000000..8fbdc50 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/arg.rst
@@ -0,0 +1,564 @@ +.. 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. + +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. + +These formats allow to access an object as a contiguous chunk of memory. +You don't have to provide raw storage for the returned unicode or bytes +area. Also, you won't have to release any memory yourself, except with the +``es``, ``es#``, ``et`` and ``et#`` formats. + +``s`` (string or Unicode) [const char \*] + Convert a Python string or Unicode object to a C pointer to a character + string. You must not provide storage for the string itself; a pointer to + an existing string is stored into the character pointer variable whose + address you pass. The C string is NUL-terminated. The Python string must + not contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is + raised. Unicode objects are converted to C strings using the default + encoding. If this conversion fails, a :exc:`UnicodeError` is raised. + +``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :c:type:`Py_ssize_t`, see below)] + This variant on ``s`` stores into two C variables, the first one a pointer + to a character string, the second one its length. In this case the Python + string may contain embedded null bytes. Unicode objects pass back a + pointer to the default encoded string version of the object if such a + conversion is possible. All other read-buffer compatible objects pass back + a reference to the raw internal data representation. + + Starting with Python 2.5 the type of the length argument can be controlled + by defining the macro :c:macro:`PY_SSIZE_T_CLEAN` before including + :file:`Python.h`. If the macro is defined, length is a :c:type:`Py_ssize_t` + rather than an int. + +``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer] + Similar to ``s#``, this code fills a Py_buffer structure provided by the + caller. The buffer gets locked, so that the caller can subsequently use + the buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is + responsible for calling ``PyBuffer_Release`` with the structure after it + has processed the data. + + .. versionadded:: 2.6 + +``z`` (string, Unicode 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#`` (string, Unicode, ``None`` or any read buffer compatible object) [const char \*, int] + This is to ``s#`` as ``z`` is to ``s``. + +``z*`` (string, Unicode, ``None`` or any buffer compatible object) [Py_buffer] + This is to ``s*`` as ``z`` is to ``s``. + + .. versionadded:: 2.6 + +``u`` (Unicode) [Py_UNICODE \*] + Convert a Python Unicode object to a C pointer to a NUL-terminated buffer + of 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to + provide storage for the Unicode data buffer; a pointer to the existing + Unicode data is stored into the :c:type:`Py_UNICODE` pointer variable whose + address you pass. + +``u#`` (Unicode) [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. Non-Unicode objects + are handled by interpreting their read-buffer pointer as pointer to a + :c:type:`Py_UNICODE` array. + +``es`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer] + This variant on ``s`` is used for encoding Unicode and objects convertible + to 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 the default 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`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer] + Same as ``es`` except that 8-bit string objects are passed through without + recoding them. Instead, the implementation assumes that the string object + uses the encoding passed in as parameter. + +``es#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length] + This variant on ``s#`` is used for encoding Unicode and objects convertible + to 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 the default 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#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length] + Same as ``es#`` except that string objects are passed through without + recoding them. Instead, the implementation assumes that the string object + uses the encoding passed in as parameter. + +``b`` (integer) [unsigned char] + Convert a nonnegative Python integer to an unsigned tiny int, stored in a C + :c:type:`unsigned char`. + +``B`` (integer) [unsigned char] + Convert a Python integer to a tiny int without overflow checking, stored in + a C :c:type:`unsigned char`. + + .. versionadded:: 2.3 + +``h`` (integer) [short int] + Convert a Python integer to a C :c:type:`short int`. + +``H`` (integer) [unsigned short int] + Convert a Python integer to a C :c:type:`unsigned short int`, without + overflow checking. + + .. versionadded:: 2.3 + +``i`` (integer) [int] + Convert a Python integer to a plain C :c:type:`int`. + +``I`` (integer) [unsigned int] + Convert a Python integer to a C :c:type:`unsigned int`, without overflow + checking. + + .. versionadded:: 2.3 + +``l`` (integer) [long int] + Convert a Python integer to a C :c:type:`long int`. + +``k`` (integer) [unsigned long] + Convert a Python integer or long integer to a C :c:type:`unsigned long` + without overflow checking. + + .. versionadded:: 2.3 + +``L`` (integer) [PY_LONG_LONG] + Convert a Python integer to a C :c:type:`long long`. This format is only + available on platforms that support :c:type:`long long` (or :c:type:`_int64` + on Windows). + +``K`` (integer) [unsigned PY_LONG_LONG] + Convert a Python integer or long integer to a C :c:type:`unsigned long long` + without overflow checking. This format is only available on platforms that + support :c:type:`unsigned long long` (or :c:type:`unsigned _int64` on + Windows). + + .. versionadded:: 2.3 + +``n`` (integer) [Py_ssize_t] + Convert a Python integer or long integer to a C :c:type:`Py_ssize_t`. + + .. versionadded:: 2.5 + +``c`` (string of length 1) [char] + Convert a Python character, represented as a string of length 1, to a C + :c:type:`char`. + +``f`` (float) [float] + Convert a Python floating point number to a C :c:type:`float`. + +``d`` (float) [double] + Convert a Python floating point number to a C :c:type:`double`. + +``D`` (complex) [Py_complex] + Convert a Python complex number to a C :c:type:`Py_complex` structure. + +``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&`` (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. + +``S`` (string) [PyStringObject \*] + Like ``O`` but requires that the Python object is a string object. Raises + :exc:`TypeError` if the object is not a string object. The C variable may + also be declared as :c:type:`PyObject\*`. + +``U`` (Unicode string) [PyUnicodeObject \*] + Like ``O`` but requires that the Python object is a Unicode object. Raises + :exc:`TypeError` if the object is not a Unicode object. The C variable may + also be declared as :c:type:`PyObject\*`. + +``t#`` (read-only character buffer) [char \*, int] + Like ``s#``, but accepts any object which implements the read-only buffer + interface. The :c:type:`char\*` variable is set to point to the first byte + of the buffer, and the :c:type:`int` is set to the length of the buffer. + Only single-segment buffer objects are accepted; :exc:`TypeError` is raised + for all others. + +``w`` (read-write character buffer) [char \*] + Similar to ``s``, but accepts any object which implements the read-write + buffer interface. The caller must determine the length of the buffer by + other means, or use ``w#`` instead. Only single-segment buffer objects are + accepted; :exc:`TypeError` is raised for all others. + +``w#`` (read-write character buffer) [char \*, Py_ssize_t] + Like ``s#``, but accepts any object which implements the read-write buffer + interface. The :c:type:`char \*` variable is set to point to the first byte + of the buffer, and the :c:type:`Py_ssize_t` is set to the length of the + buffer. Only single-segment buffer objects are accepted; :exc:`TypeError` + is raised for all others. + +``w*`` (read-write byte-oriented buffer) [Py_buffer] + This is to ``w`` what ``s*`` is to ``s``. + + .. versionadded:: 2.6 + +``(items)`` (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. + + .. note:: + + Prior to Python version 1.5.2, this format specifier only accepted a + tuple containing the individual parameters, not an arbitrary sequence. + Code which previously caused :exc:`TypeError` to be raised here may now + proceed without an exception. This is not expected to be a problem for + existing code. + +It is possible to pass Python long integers where integers are requested; +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). + +``:`` + 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. + + +.. 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. Returns true on success; on failure, it + returns false and raises the appropriate exception. + + +.. 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_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. 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) + + .. versionadded:: 2.2 + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *min* and *max*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. 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`` (string) [char \*] + Convert a null-terminated C string to a Python object. If the C string + pointer is *NULL*, ``None`` is used. + + ``s#`` (string) [char \*, int] + Convert a C string and its length to a Python object. If the C string + pointer is *NULL*, the length is ignored and ``None`` is returned. + + ``z`` (string or ``None``) [char \*] + Same as ``s``. + + ``z#`` (string or ``None``) [char \*, int] + Same as ``s#``. + + ``u`` (Unicode string) [Py_UNICODE \*] + Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a + Python Unicode object. If the Unicode buffer pointer is *NULL*, + ``None`` is returned. + + ``u#`` (Unicode string) [Py_UNICODE \*, int] + Convert a Unicode (UCS-2 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. + + ``i`` (integer) [int] + Convert a plain C :c:type:`int` to a Python integer object. + + ``b`` (integer) [char] + Convert a plain C :c:type:`char` to a Python integer object. + + ``h`` (integer) [short int] + Convert a plain C :c:type:`short int` to a Python integer object. + + ``l`` (integer) [long int] + Convert a C :c:type:`long int` to a Python integer object. + + ``B`` (integer) [unsigned char] + Convert a C :c:type:`unsigned char` to a Python integer object. + + ``H`` (integer) [unsigned short int] + Convert a C :c:type:`unsigned short int` to a Python integer object. + + ``I`` (integer/long) [unsigned int] + Convert a C :c:type:`unsigned int` to a Python integer object or a Python + long integer object, if it is larger than ``sys.maxint``. + + ``k`` (integer/long) [unsigned long] + Convert a C :c:type:`unsigned long` to a Python integer object or a + Python long integer object, if it is larger than ``sys.maxint``. + + ``L`` (long) [PY_LONG_LONG] + Convert a C :c:type:`long long` to a Python long integer object. Only + available on platforms that support :c:type:`long long`. + + ``K`` (long) [unsigned PY_LONG_LONG] + Convert a C :c:type:`unsigned long long` to a Python long integer object. + Only available on platforms that support :c:type:`unsigned long long`. + + ``n`` (int) [Py_ssize_t] + Convert a C :c:type:`Py_ssize_t` to a Python integer or long integer. + + .. versionadded:: 2.5 + + ``c`` (string of length 1) [char] + Convert a C :c:type:`int` representing a character to a Python string of + length 1. + + ``d`` (float) [double] + Convert a C :c:type:`double` to a Python floating point number. + + ``f`` (float) [float] + Same as ``d``. + + ``D`` (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)`` (tuple) [*matching-items*] + Convert a sequence of C values to a Python tuple with the same number of + items. + + ``[items]`` (list) [*matching-items*] + Convert a sequence of C values to a Python list with the same number of + items. + + ``{items}`` (dictionary) [*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.
diff --git a/Python-2.7.5/Doc/c-api/bool.rst b/Python-2.7.5/Doc/c-api/bool.rst new file mode 100644 index 0000000..fede348 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/bool.rst
@@ -0,0 +1,54 @@ +.. 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`. + + .. versionadded:: 2.3 + + +.. 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. + + .. versionadded:: 2.4 + + +.. c:macro:: Py_RETURN_TRUE + + Return :const:`Py_True` from a function, properly incrementing its reference + count. + + .. versionadded:: 2.4 + + +.. 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*. + + .. versionadded:: 2.3
diff --git a/Python-2.7.5/Doc/c-api/buffer.rst b/Python-2.7.5/Doc/c-api/buffer.rst new file mode 100644 index 0000000..e028369 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/buffer.rst
@@ -0,0 +1,450 @@ +.. highlightlang:: c + +.. _bufferobjects: + +Buffers and Memoryview Objects +------------------------------ + +.. sectionauthor:: Greg Stein <[email protected]> +.. sectionauthor:: Benjamin Peterson + + +.. index:: + object: buffer + single: buffer interface + +Python objects implemented in C can export a group of functions called the +"buffer interface." These functions can be used by an object to expose its +data in a raw, byte-oriented format. Clients of the object can use the buffer +interface to access the object data directly, without needing to copy it +first. + +Two examples of objects that support the buffer interface are strings and +arrays. The string object exposes the character contents in the buffer +interface's byte-oriented form. An array can also expose its contents, but it +should be noted that array elements may be multi-byte values. + +An example user of the buffer interface is the file object's :meth:`write` +method. Any object that can export a series of bytes through the buffer +interface can be written to a file. There are a number of format codes to +:c:func:`PyArg_ParseTuple` that operate against an object's buffer interface, +returning data from the target object. + +Starting from version 1.6, Python has been providing Python-level buffer +objects and a C-level buffer API so that any built-in or used-defined type can +expose its characteristics. Both, however, have been deprecated because of +various shortcomings, and have been officially removed in Python 3 in favour +of a new C-level buffer API and a new Python-level object named +:class:`memoryview`. + +The new buffer API has been backported to Python 2.6, and the +:class:`memoryview` object has been backported to Python 2.7. It is strongly +advised to use them rather than the old APIs, unless you are blocked from +doing so for compatibility reasons. + + +The new-style Py_buffer struct +============================== + + +.. c:type:: Py_buffer + + .. c:member:: void *buf + + A pointer to the start of the memory for the object. + + .. c:member:: Py_ssize_t len + :noindex: + + The total length of the memory in bytes. + + .. c:member:: int readonly + + An indicator of whether the buffer is read only. + + .. c:member:: const char *format + :noindex: + + A *NULL* terminated string in :mod:`struct` module style syntax giving + the contents of the elements available through the buffer. If this is + *NULL*, ``"B"`` (unsigned bytes) is assumed. + + .. c:member:: int ndim + + The number of dimensions the memory represents as a multi-dimensional + array. If it is 0, :c:data:`strides` and :c:data:`suboffsets` must be + *NULL*. + + .. c:member:: Py_ssize_t *shape + + An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the + shape of the memory as a multi-dimensional array. Note that + ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to + :c:data:`len`. + + .. c:member:: Py_ssize_t *strides + + An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim` giving the + number of bytes to skip to get to a new element in each dimension. + + .. c:member:: Py_ssize_t *suboffsets + + An array of :c:type:`Py_ssize_t`\s the length of :c:data:`ndim`. If these + suboffset numbers are greater than or equal to 0, then the value stored + along the indicated dimension is a pointer and the suboffset value + dictates how many bytes to add to the pointer after de-referencing. A + suboffset value that it negative indicates that no de-referencing should + occur (striding in a contiguous memory block). + + Here is a function that returns a pointer to the element in an N-D array + pointed to by an N-dimesional 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; + } + + + .. c:member:: Py_ssize_t itemsize + + This is a storage for the itemsize (in bytes) of each element of the + shared memory. It is technically un-necessary as it can be obtained + using :c:func:`PyBuffer_SizeFromFormat`, however an exporter may know + this information without parsing the format string and it is necessary + to know the itemsize for proper interpretation of striding. Therefore, + storing it is more convenient and faster. + + .. 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 should never alter this + value. + + +Buffer related functions +======================== + + +.. c:function:: int PyObject_CheckBuffer(PyObject *obj) + + Return 1 if *obj* supports the buffer interface otherwise 0. + + +.. c:function:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags) + + Export *obj* into a :c:type:`Py_buffer`, *view*. These arguments must + never be *NULL*. The *flags* argument is a bit field indicating what + kind of buffer the caller is prepared to deal with and therefore what + kind of buffer the exporter is allowed to return. The buffer interface + allows for complicated memory sharing possibilities, but some caller may + not be able to handle all the complexity but may want to see if the + exporter will let them take a simpler view to its memory. + + Some exporters may not be able to share memory in every possible way and + may need to raise errors to signal to some consumers that something is + just not possible. These errors should be a :exc:`BufferError` unless + there is another error that is actually causing the problem. The + exporter can use flags information to simplify how much of the + :c:data:`Py_buffer` structure is filled in with non-default values and/or + raise an error if the object can't support a simpler view of its memory. + + 0 is returned on success and -1 on error. + + The following table gives possible values to the *flags* arguments. + + +-------------------------------+---------------------------------------------------+ + | Flag | Description | + +===============================+===================================================+ + | :c:macro:`PyBUF_SIMPLE` | This is the default flag state. The returned | + | | buffer may or may not have writable memory. The | + | | format of the data will be assumed to be unsigned | + | | bytes. This is a "stand-alone" flag constant. It | + | | never needs to be '|'d to the others. The exporter| + | | will raise an error if it cannot provide such a | + | | contiguous buffer of bytes. | + | | | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is | + | | not writable, then raise an error. | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_STRIDES` | This implies :c:macro:`PyBUF_ND`. The returned | + | | buffer must provide strides information (i.e. the | + | | strides cannot be NULL). This would be used when | + | | the consumer can handle strided, discontiguous | + | | arrays. Handling strides automatically assumes | + | | you can handle shape. The exporter can raise an | + | | error if a strided representation of the data is | + | | not possible (i.e. without the suboffsets). | + | | | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_ND` | The returned buffer must provide shape | + | | information. The memory will be assumed C-style | + | | contiguous (last dimension varies the | + | | fastest). The exporter may raise an error if it | + | | cannot provide this kind of contiguous buffer. If | + | | this is not given then shape will be *NULL*. | + | | | + | | | + | | | + +-------------------------------+---------------------------------------------------+ + |:c:macro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned | + |:c:macro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last | + |:c:macro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous | + | | (first dimension varies the fastest) or either | + | | one. All of these flags imply | + | | :c:macro:`PyBUF_STRIDES` and guarantee that the | + | | strides buffer info structure will be filled in | + | | correctly. | + | | | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have | + | | suboffsets information (which can be NULL if no | + | | suboffsets are needed). This can be used when | + | | the consumer can handle indirect array | + | | referencing implied by these suboffsets. This | + | | implies :c:macro:`PyBUF_STRIDES`. | + | | | + | | | + | | | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_FORMAT` | The returned buffer must have true format | + | | information if this flag is provided. This would | + | | be used when the consumer is going to be checking | + | | for what 'kind' of data is actually stored. An | + | | exporter should always be able to provide this | + | | information if requested. If format is not | + | | explicitly requested then the format must be | + | | returned as *NULL* (which means ``'B'``, or | + | | unsigned bytes) | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | | + | | PyBUF_WRITABLE)``. | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. | + | | | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | | + | | PyBUF_FORMAT | PyBUF_WRITABLE)``. | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | | + | | PyBUF_FORMAT)``. | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | | + | | PyBUF_FORMAT | PyBUF_WRITABLE)``. | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | | + | | PyBUF_FORMAT)``. | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | | + | | PyBUF_WRITABLE)``. | + +-------------------------------+---------------------------------------------------+ + | :c:macro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. | + | | | + +-------------------------------+---------------------------------------------------+ + + +.. c:function:: void PyBuffer_Release(Py_buffer *view) + + Release the buffer *view*. This should be called when the buffer + is no longer being used as it may free memory from it. + + +.. c:function:: Py_ssize_t PyBuffer_SizeFromFormat(const char *) + + Return the implied :c:data:`~Py_buffer.itemsize` from the struct-stype + :c:data:`~Py_buffer.format`. + + +.. c:function:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran) + + Return 1 if the memory defined by the *view* is C-style (*fortran* is + ``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one + (*fortran* is ``'A'``). Return 0 otherwise. + + +.. c:function:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran) + + Fill the *strides* array with byte-strides of a contiguous (C-style if + *fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'``) array of the + given shape with the given number of bytes per element. + + +.. c:function:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags) + + Fill in a buffer-info structure, *view*, correctly for an exporter that can + only share a contiguous chunk of memory of "unsigned bytes" of the given + length. Return 0 on success and -1 (with raising an error) on error. + + +MemoryView objects +================== + +.. versionadded:: 2.7 + +A :class:`memoryview` object exposes the new C level buffer interface 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 defines the new buffer + interface. + + +.. c:function:: PyObject *PyMemoryView_FromBuffer(Py_buffer *view) + + Create a memoryview object wrapping the given buffer-info structure *view*. + The memoryview object then owns the buffer, which means you shouldn't + try to release it yourself: it will be released on deallocation of the + memoryview object. + + +.. c:function:: PyObject *PyMemoryView_GetContiguous(PyObject *obj, int buffertype, char order) + + Create a memoryview object to a 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 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 *obj) + + Return a pointer to the buffer-info structure wrapped by the given + object. The object **must** be a memoryview instance; this macro doesn't + check its type, you must do it yourself or you will risk crashes. + + +Old-style buffer objects +======================== + +.. index:: single: PyBufferProcs + +More information on the old buffer interface is provided in the section +:ref:`buffer-structs`, under the description for :c:type:`PyBufferProcs`. + +A "buffer object" is defined in the :file:`bufferobject.h` header (included by +:file:`Python.h`). These objects look very similar to string objects at the +Python programming level: they support slicing, indexing, concatenation, and +some other standard string operations. However, their data can come from one +of two sources: from a block of memory, or from another object which exports +the buffer interface. + +Buffer objects are useful as a way to expose the data from another object's +buffer interface 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. + + +.. c:type:: PyBufferObject + + This subtype of :c:type:`PyObject` represents a buffer object. + + +.. c:var:: PyTypeObject PyBuffer_Type + + .. index:: single: BufferType (in module types) + + The instance of :c:type:`PyTypeObject` which represents the Python buffer type; + it is the same object as ``buffer`` and ``types.BufferType`` in the Python + layer. . + + +.. c:var:: int Py_END_OF_BUFFER + + This constant may be passed as the *size* parameter to + :c:func:`PyBuffer_FromObject` or :c:func:`PyBuffer_FromReadWriteObject`. It + indicates that the new :c:type:`PyBufferObject` should refer to *base* + object from the specified *offset* to the end of its exported buffer. + Using this enables the caller to avoid querying the *base* object for its + length. + + +.. c:function:: int PyBuffer_Check(PyObject *p) + + Return true if the argument has type :c:data:`PyBuffer_Type`. + + +.. c:function:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) + + Return a new read-only buffer object. This raises :exc:`TypeError` if + *base* doesn't support the read-only buffer protocol or doesn't provide + exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is + less than zero. The buffer will hold a reference to the *base* object, and + the buffer's contents will refer to the *base* object's buffer interface, + starting as position *offset* and extending for *size* bytes. If *size* is + :const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the + length of the *base* object's exported buffer data. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *offset* and *size*. This + might require changes in your code for properly supporting 64-bit + systems. + + +.. c:function:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) + + Return a new writable buffer object. Parameters and exceptions are similar + to those for :c:func:`PyBuffer_FromObject`. If the *base* object does not + export the writeable buffer protocol, then :exc:`TypeError` is raised. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *offset* and *size*. This + might require changes in your code for properly supporting 64-bit + systems. + + +.. c:function:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size) + + Return a new read-only buffer object that reads from a specified location + in memory, with a specified size. The caller is responsible for ensuring + that the memory buffer, passed in as *ptr*, is not deallocated while the + returned buffer object exists. Raises :exc:`ValueError` if *size* is less + than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the + *size* parameter; :exc:`ValueError` will be raised in that case. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size) + + Similar to :c:func:`PyBuffer_FromMemory`, but the returned buffer is + writable. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyBuffer_New(Py_ssize_t size) + + Return a new writable buffer object that maintains its own memory buffer of + *size* bytes. :exc:`ValueError` is returned if *size* is not zero or + positive. Note that the memory buffer (as returned by + :c:func:`PyObject_AsWriteBuffer`) is not specifically aligned. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems.
diff --git a/Python-2.7.5/Doc/c-api/bytearray.rst b/Python-2.7.5/Doc/c-api/bytearray.rst new file mode 100644 index 0000000..858c8db --- /dev/null +++ b/Python-2.7.5/Doc/c-api/bytearray.rst
@@ -0,0 +1,87 @@ +.. highlightlang:: c + +.. _bytearrayobjects: + +Byte Array Objects +------------------ + +.. index:: object: bytearray + +.. versionadded:: 2.6 + + +.. 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 ``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 + buffer protocol. + + .. 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. + + +.. 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`.
diff --git a/Python-2.7.5/Doc/c-api/capsule.rst b/Python-2.7.5/Doc/c-api/capsule.rst new file mode 100644 index 0000000..6f6250f --- /dev/null +++ b/Python-2.7.5/Doc/c-api/capsule.rst
@@ -0,0 +1,150 @@ +.. highlightlang:: c + +.. _capsules: + +Capsules +-------- + +.. index:: object: Capsule + +Refer to :ref:`using-capsules` for more information on using these objects. + + +.. 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*. However, if :c:func:`PyCapsule_Import` failed to + import the module, and *no_block* was true, no exception is set. + +.. 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.
diff --git a/Python-2.7.5/Doc/c-api/cell.rst b/Python-2.7.5/Doc/c-api/cell.rst new file mode 100644 index 0000000..427259c --- /dev/null +++ b/Python-2.7.5/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.
diff --git a/Python-2.7.5/Doc/c-api/class.rst b/Python-2.7.5/Doc/c-api/class.rst new file mode 100644 index 0000000..4dbe508 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/class.rst
@@ -0,0 +1,65 @@ +.. highlightlang:: c + +.. _classobjects: + +Class and Instance Objects +-------------------------- + +.. index:: object: class + +Note that the class objects described here represent old-style classes, which +will go away in Python 3. When creating new types for extension modules, you +will want to work with type objects (section :ref:`typeobjects`). + + +.. c:type:: PyClassObject + + The C structure of the objects used to describe built-in classes. + + +.. c:var:: PyObject* PyClass_Type + + .. index:: single: ClassType (in module types) + + This is the type object for class objects; it is the same object as + ``types.ClassType`` in the Python layer. + + +.. c:function:: int PyClass_Check(PyObject *o) + + Return true if the object *o* is a class object, including instances of types + derived from the standard class object. Return false in all other cases. + + +.. c:function:: int PyClass_IsSubclass(PyObject *klass, PyObject *base) + + Return true if *klass* is a subclass of *base*. Return false in all other cases. + + +.. index:: object: instance + +There are very few functions specific to instance objects. + + +.. c:var:: PyTypeObject PyInstance_Type + + Type object for class instances. + + +.. c:function:: int PyInstance_Check(PyObject *obj) + + Return true if *obj* is an instance. + + +.. c:function:: PyObject* PyInstance_New(PyObject *class, PyObject *arg, PyObject *kw) + + Create a new instance of a specific class. The parameters *arg* and *kw* are + used as the positional and keyword parameters to the object's constructor. + + +.. c:function:: PyObject* PyInstance_NewRaw(PyObject *class, PyObject *dict) + + Create a new instance of a specific class without calling its constructor. + *class* is the class of new object. The *dict* parameter will be used as the + object's :attr:`__dict__`; if *NULL*, a new dictionary will be created for the + instance.
diff --git a/Python-2.7.5/Doc/c-api/cobject.rst b/Python-2.7.5/Doc/c-api/cobject.rst new file mode 100644 index 0000000..eafac0e --- /dev/null +++ b/Python-2.7.5/Doc/c-api/cobject.rst
@@ -0,0 +1,59 @@ +.. highlightlang:: c + +.. _cobjects: + +CObjects +-------- + +.. index:: object: CObject + + +.. warning:: + + The CObject API is deprecated as of Python 2.7. Please switch to the new + :ref:`capsules` API. + +.. c:type:: PyCObject + + 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:function:: int PyCObject_Check(PyObject *p) + + Return true if its argument is a :c:type:`PyCObject`. + + +.. c:function:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *)) + + Create a :c:type:`PyCObject` from the ``void *`` *cobj*. The *destr* function + will be called when the object is reclaimed, unless it is *NULL*. + + +.. c:function:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *)) + + Create a :c:type:`PyCObject` from the :c:type:`void \*` *cobj*. The *destr* + function will be called when the object is reclaimed. The *desc* argument can + be used to pass extra callback data for the destructor function. + + +.. c:function:: void* PyCObject_AsVoidPtr(PyObject* self) + + Return the object :c:type:`void \*` that the :c:type:`PyCObject` *self* was + created with. + + +.. c:function:: void* PyCObject_GetDesc(PyObject* self) + + Return the description :c:type:`void \*` that the :c:type:`PyCObject` *self* was + created with. + + +.. c:function:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj) + + Set the void pointer inside *self* to *cobj*. The :c:type:`PyCObject` must not + have an associated destructor. Return true on success, false on failure.
diff --git a/Python-2.7.5/Doc/c-api/code.rst b/Python-2.7.5/Doc/c-api/code.rst new file mode 100644 index 0000000..7d9b4b6 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/code.rst
@@ -0,0 +1,50 @@ +.. highlightlang:: c + +.. _codeobjects: + +Code Objects +------------ + +.. sectionauthor:: Jeffrey Yasskin <[email protected]> + + +.. index:: + object: code + +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(PyObject *co) + + Return the number of free variables in *co*. + +.. c:function:: PyCodeObject *PyCode_New(int argcount, 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:: int 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 + :keyword:`exec` or :func:`eval` the resulting code object.
diff --git a/Python-2.7.5/Doc/c-api/codec.rst b/Python-2.7.5/Doc/c-api/codec.rst new file mode 100644 index 0000000..8207ae0 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/codec.rst
@@ -0,0 +1,118 @@ +.. _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*. + +.. 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:`IncrementalEncoder` object for the given *encoding*. + +.. c:function:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors) + + Get an :class:`IncrementalDecoder` object for the given *encoding*. + +.. c:function:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors) + + Get a :class:`StreamReader` factory function for the given *encoding*. + +.. c:function:: PyObject* PyCodec_StreamWriter(const char *encoding, PyObject *stream, const char *errors) + + Get a :class:`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``). +
diff --git a/Python-2.7.5/Doc/c-api/complex.rst b/Python-2.7.5/Doc/c-api/complex.rst new file mode 100644 index 0000000..2547c1c --- /dev/null +++ b/Python-2.7.5/Doc/c-api/complex.rst
@@ -0,0 +1,139 @@ +.. 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 ``complex`` and ``types.ComplexType``. + + +.. c:function:: int PyComplex_Check(PyObject *p) + + Return true if its argument is a :c:type:`PyComplexObject` or a subtype of + :c:type:`PyComplexObject`. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. 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`. + + .. versionadded:: 2.2 + + +.. 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*. + Upon failure, this method returns ``-1.0`` as a real value. + + .. versionchanged:: 2.6 + 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.
diff --git a/Python-2.7.5/Doc/c-api/concrete.rst b/Python-2.7.5/Doc/c-api/concrete.rst new file mode 100644 index 0000000..30eb78d --- /dev/null +++ b/Python-2.7.5/Doc/c-api/concrete.rst
@@ -0,0 +1,109 @@ +.. 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:: + + int.rst + bool.rst + long.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. + +.. toctree:: + + bytearray.rst + string.rst + unicode.rst + buffer.rst + tuple.rst + list.rst + + +.. _mapobjects: + +Mapping Objects +=============== + +.. index:: object: mapping + +.. toctree:: + + dict.rst + + +.. _otherobjects: + +Other Objects +============= + +.. toctree:: + + class.rst + function.rst + method.rst + file.rst + module.rst + iterator.rst + descriptor.rst + slice.rst + weakref.rst + capsule.rst + cobject.rst + cell.rst + gen.rst + datetime.rst + set.rst + code.rst
diff --git a/Python-2.7.5/Doc/c-api/conversion.rst b/Python-2.7.5/Doc/c-api/conversion.rst new file mode 100644 index 0000000..b987469 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/conversion.rst
@@ -0,0 +1,181 @@ +.. 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:: 2.7 + + +.. c:function:: double PyOS_ascii_strtod(const char *nptr, char **endptr) + + Convert a string to a :c:type:`double`. This function behaves like the Standard C + function :c:func:`strtod` does in the C locale. It does this without changing the + current locale, since that would not be thread-safe. + + :c:func:`PyOS_ascii_strtod` should typically be used for reading configuration + files or other non-user input that should be locale independent. + + See the Unix man page :manpage:`strtod(2)` for details. + + .. versionadded:: 2.4 + + .. deprecated:: 2.7 + Use :c:func:`PyOS_string_to_double` instead. + + + +.. c:function:: char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d) + + Convert a :c:type:`double` to a string using the ``'.'`` as the decimal + separator. *format* is a :c:func:`printf`\ -style format string specifying the + number format. Allowed conversion characters are ``'e'``, ``'E'``, ``'f'``, + ``'F'``, ``'g'`` and ``'G'``. + + The return value is a pointer to *buffer* with the converted string or NULL if + the conversion failed. + + .. versionadded:: 2.4 + .. deprecated:: 2.7 + This function is removed in Python 2.7 and 3.1. Use :func:`PyOS_double_to_string` + instead. + + +.. 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:: 2.7 + + +.. c:function:: double PyOS_ascii_atof(const char *nptr) + + Convert a string to a :c:type:`double` in a locale-independent way. + + See the Unix man page :manpage:`atof(2)` for details. + + .. versionadded:: 2.4 + + .. deprecated:: 3.1 + Use :c:func:`PyOS_string_to_double` instead. + + +.. c:function:: char* PyOS_stricmp(char *s1, char *s2) + + Case insensitive comparison of strings. The function works almost + identically to :c:func:`strcmp` except that it ignores the case. + + .. versionadded:: 2.6 + + +.. c:function:: char* PyOS_strnicmp(char *s1, 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. + + .. versionadded:: 2.6
diff --git a/Python-2.7.5/Doc/c-api/datetime.rst b/Python-2.7.5/Doc/c-api/datetime.rst new file mode 100644 index 0000000..e2d832c --- /dev/null +++ b/Python-2.7.5/Doc/c-api/datetime.rst
@@ -0,0 +1,239 @@ +.. 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*. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDate_CheckExact(PyObject *ob) + + Return true if *ob* is of type :c:data:`PyDateTime_DateType`. *ob* must not be + *NULL*. + + .. versionadded:: 2.4 + + +.. 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*. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDateTime_CheckExact(PyObject *ob) + + Return true if *ob* is of type :c:data:`PyDateTime_DateTimeType`. *ob* must not + be *NULL*. + + .. versionadded:: 2.4 + + +.. 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*. + + .. versionadded:: 2.4 + + +.. c:function:: int PyTime_CheckExact(PyObject *ob) + + Return true if *ob* is of type :c:data:`PyDateTime_TimeType`. *ob* must not be + *NULL*. + + .. versionadded:: 2.4 + + +.. 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*. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDelta_CheckExact(PyObject *ob) + + Return true if *ob* is of type :c:data:`PyDateTime_DeltaType`. *ob* must not be + *NULL*. + + .. versionadded:: 2.4 + + +.. 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*. + + .. versionadded:: 2.4 + + +.. c:function:: int PyTZInfo_CheckExact(PyObject *ob) + + Return true if *ob* is of type :c:data:`PyDateTime_TZInfoType`. *ob* must not be + *NULL*. + + .. versionadded:: 2.4 + +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. + + .. versionadded:: 2.4 + + +.. 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. + + .. versionadded:: 2.4 + + +.. 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. + + .. versionadded:: 2.4 + + +.. 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. + + .. versionadded:: 2.4 + +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. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDateTime_GET_MONTH(PyDateTime_Date *o) + + Return the month, as an int from 1 through 12. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDateTime_GET_DAY(PyDateTime_Date *o) + + Return the day, as an int from 1 through 31. + + .. versionadded:: 2.4 + +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. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o) + + Return the minute, as an int from 0 through 59. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o) + + Return the second, as an int from 0 through 59. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o) + + Return the microsecond, as an int from 0 through 999999. + + .. versionadded:: 2.4 + +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. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDateTime_TIME_GET_MINUTE(PyDateTime_Time *o) + + Return the minute, as an int from 0 through 59. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDateTime_TIME_GET_SECOND(PyDateTime_Time *o) + + Return the second, as an int from 0 through 59. + + .. versionadded:: 2.4 + + +.. c:function:: int PyDateTime_TIME_GET_MICROSECOND(PyDateTime_Time *o) + + Return the microsecond, as an int from 0 through 999999. + + .. versionadded:: 2.4 + +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()``. + + .. versionadded:: 2.4 + + +.. 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()``. + + .. versionadded:: 2.4
diff --git a/Python-2.7.5/Doc/c-api/descriptor.rst b/Python-2.7.5/Doc/c-api/descriptor.rst new file mode 100644 index 0000000..43baeaf --- /dev/null +++ b/Python-2.7.5/Doc/c-api/descriptor.rst
@@ -0,0 +1,55 @@ +.. 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. + + +.. c:var:: PyTypeObject PyProperty_Type + + The type object for the built-in descriptor types. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyDescr_NewGetSet(PyTypeObject *type, struct PyGetSetDef *getset) + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyDescr_NewMember(PyTypeObject *type, struct PyMemberDef *meth) + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyDescr_NewMethod(PyTypeObject *type, struct PyMethodDef *meth) + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyDescr_NewWrapper(PyTypeObject *type, struct wrapperbase *wrapper, void *wrapped) + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyDescr_NewClassMethod(PyTypeObject *type, PyMethodDef *method) + + .. versionadded:: 2.3 + + +.. 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. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyWrapper_New(PyObject *, PyObject *) + + .. versionadded:: 2.2
diff --git a/Python-2.7.5/Doc/c-api/dict.rst b/Python-2.7.5/Doc/c-api/dict.rst new file mode 100644 index 0000000..3e967bd --- /dev/null +++ b/Python-2.7.5/Doc/c-api/dict.rst
@@ -0,0 +1,233 @@ +.. 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 + + .. index:: + single: DictType (in module types) + single: DictionaryType (in module types) + + This instance of :c:type:`PyTypeObject` represents the Python dictionary + type. This is exposed to Python programs as ``dict`` and + ``types.DictType``. + + +.. 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. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. 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. + + .. versionadded:: 2.4 + + +.. c:function:: PyObject* PyDict_New() + + Return a new empty dictionary, or *NULL* on failure. + + +.. c:function:: PyObject* PyDictProxy_New(PyObject *dict) + + Return a proxy object for a mapping which enforces read-only behavior. + This is normally used to create a proxy to prevent modification of the + dictionary for non-dynamic class types. + + .. versionadded:: 2.2 + + +.. 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``. + + .. versionadded:: 2.4 + + +.. c:function:: PyObject* PyDict_Copy(PyObject *p) + + Return a new dictionary that contains the same key-value pairs as *p*. + + .. versionadded:: 1.6 + + +.. 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: PyString_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 + ``PyString_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, 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. + + +.. 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\*`. + + +.. c:function:: PyObject* PyDict_Items(PyObject *p) + + Return a :c:type:`PyListObject` containing all the items from the + dictionary, as in the dictionary method :meth:`dict.items`. + + +.. c:function:: PyObject* PyDict_Keys(PyObject *p) + + Return a :c:type:`PyListObject` containing all the keys from the dictionary, + as in the dictionary method :meth:`dict.keys`. + + +.. c:function:: PyObject* PyDict_Values(PyObject *p) + + Return a :c:type:`PyListObject` containing all the values from the + dictionary *p*, as in the dictionary method :meth:`dict.values`. + + +.. 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. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. 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 + (since Python 2.1) 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)) { + int i = PyInt_AS_LONG(value) + 1; + PyObject *o = PyInt_FromLong(i); + if (o == NULL) + return -1; + if (PyDict_SetItem(self->dict, key, o) < 0) { + Py_DECREF(o); + return -1; + } + Py_DECREF(o); + } + + .. versionchanged:: 2.5 + This function used an :c:type:`int *` type for *ppos*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionadded:: 2.2 + + +.. c:function:: int PyDict_Update(PyObject *a, PyObject *b) + + This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in + Python. Return ``0`` on success or ``-1`` if an exception was raised. + + .. versionadded:: 2.2 + + +.. 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 + + .. versionadded:: 2.2
diff --git a/Python-2.7.5/Doc/c-api/exceptions.rst b/Python-2.7.5/Doc/c-api/exceptions.rst new file mode 100644 index 0000000..91964d0 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/exceptions.rst
@@ -0,0 +1,643 @@ +.. highlightlang:: c + + +.. _exceptionhandling: + +****************** +Exception Handling +****************** + +The functions described in this chapter will let you handle and raise Python +exceptions. It is important to understand some of the basics of Python +exception handling. It works somewhat like the Unix :c:data:`errno` variable: +there is a global indicator (per thread) of the last error that occurred. Most +functions don't clear this on success, but will set it to indicate the cause of +the error on failure. Most functions also return an error indicator, usually +*NULL* if they are supposed to return a pointer, or ``-1`` if they return an +integer (exception: the :c:func:`PyArg_\*` functions return ``1`` for success and +``0`` for failure). + +When a function must fail because some function it called failed, it generally +doesn't set the error indicator; the function it called already set it. It is +responsible for either handling the error and clearing the exception or +returning after cleaning up any resources it holds (such as object references or +memory allocations); it should *not* continue normally if it is not prepared to +handle the error. If returning due to an error, it is important to indicate to +the caller that an error has been set. If the error is not handled or carefully +propagated, additional calls into the Python/C API may not behave as intended +and may fail in mysterious ways. + +.. index:: + single: exc_type (in module sys) + single: exc_value (in module sys) + single: exc_traceback (in module sys) + +The error indicator consists of three Python objects corresponding to the +Python variables ``sys.exc_type``, ``sys.exc_value`` and ``sys.exc_traceback``. +API functions exist to interact with the error indicator in various ways. There +is a separate error indicator for each thread. + +.. XXX Order of these should be more thoughtful. + Either alphabetical or some kind of structure. + + +.. c:function:: void PyErr_PrintEx(int set_sys_last_vars) + + Print a standard traceback to ``sys.stderr`` and clear the error indicator. + Call this function only when the error indicator is set. (Otherwise it will + cause a fatal error!) + + If *set_sys_last_vars* is nonzero, the variables :data:`sys.last_type`, + :data:`sys.last_value` and :data:`sys.last_traceback` will be set to the + type, value and traceback of the printed exception, respectively. + + +.. c:function:: void PyErr_Print() + + Alias for ``PyErr_PrintEx(1)``. + + +.. c:function:: PyObject* PyErr_Occurred() + + Test whether the error indicator is set. If set, return the exception *type* + (the first argument to the last call to one of the :c:func:`PyErr_Set\*` + functions or to :c:func:`PyErr_Restore`). If not set, return *NULL*. You do not + own a reference to the return value, so you do not need to :c:func:`Py_DECREF` + it. + + .. note:: + + Do not compare the return value to a specific exception; use + :c:func:`PyErr_ExceptionMatches` instead, shown below. (The comparison could + easily fail since the exception may be an instance instead of a class, in the + case of a class exception, or it may the a subclass of the expected exception.) + + +.. c:function:: int PyErr_ExceptionMatches(PyObject *exc) + + Equivalent to ``PyErr_GivenExceptionMatches(PyErr_Occurred(), exc)``. This + should only be called when an exception is actually set; a memory access + violation will occur if no exception has been raised. + + +.. c:function:: int PyErr_GivenExceptionMatches(PyObject *given, PyObject *exc) + + Return true if the *given* exception matches the exception in *exc*. If + *exc* is a class object, this also returns true when *given* is an instance + of a subclass. If *exc* is a tuple, all exceptions in the tuple (and + recursively in subtuples) are searched for a match. + + +.. c:function:: void PyErr_NormalizeException(PyObject**exc, PyObject**val, PyObject**tb) + + Under certain circumstances, the values returned by :c:func:`PyErr_Fetch` below + can be "unnormalized", meaning that ``*exc`` is a class object but ``*val`` is + not an instance of the same class. This function can be used to instantiate + the class in that case. If the values are already normalized, nothing happens. + The delayed normalization is implemented to improve performance. + + +.. c:function:: void PyErr_Clear() + + Clear the error indicator. If the error indicator is not set, there is no + effect. + + +.. c:function:: void PyErr_Fetch(PyObject **ptype, PyObject **pvalue, PyObject **ptraceback) + + Retrieve the error indicator into three variables whose addresses are passed. + If the error indicator is not set, set all three variables to *NULL*. If it is + set, it will be cleared and you own a reference to each object retrieved. The + value and traceback object may be *NULL* even when the type object is not. + + .. note:: + + This function is normally only used by code that needs to handle exceptions or + by code that needs to save and restore the error indicator temporarily. + + +.. c:function:: void PyErr_Restore(PyObject *type, PyObject *value, PyObject *traceback) + + Set the error indicator from the three objects. If the error indicator is + already set, it is cleared first. If the objects are *NULL*, the error + indicator is cleared. Do not pass a *NULL* type and non-*NULL* value or + traceback. The exception type should be a class. Do not pass an invalid + exception type or value. (Violating these rules will cause subtle problems + later.) This call takes away a reference to each object: you must own a + reference to each object before the call and after the call you no longer own + these references. (If you don't understand this, don't use this function. I + warned you.) + + .. note:: + + This function is normally only used by code that needs to save and restore the + error indicator temporarily; use :c:func:`PyErr_Fetch` to save the current + exception state. + + +.. c:function:: void PyErr_SetString(PyObject *type, const char *message) + + This is the most common way to set the error indicator. The first argument + specifies the exception type; it is normally one of the standard exceptions, + e.g. :c:data:`PyExc_RuntimeError`. You need not increment its reference count. + The second argument is an error message; it is converted to a string object. + + +.. c:function:: void PyErr_SetObject(PyObject *type, PyObject *value) + + This function is similar to :c:func:`PyErr_SetString` but lets you specify an + arbitrary Python object for the "value" of the exception. + + +.. c:function:: PyObject* PyErr_Format(PyObject *exception, const char *format, ...) + + This function sets the error indicator and returns *NULL*. *exception* + should be a Python exception class. The *format* and subsequent + parameters help format the error message; they have the same meaning and + values as in :c:func:`PyString_FromFormat`. + + +.. c:function:: void PyErr_SetNone(PyObject *type) + + This is a shorthand for ``PyErr_SetObject(type, Py_None)``. + + +.. c:function:: int PyErr_BadArgument() + + This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where + *message* indicates that a built-in operation was invoked with an illegal + argument. It is mostly for internal use. + + +.. c:function:: PyObject* PyErr_NoMemory() + + This is a shorthand for ``PyErr_SetNone(PyExc_MemoryError)``; it returns *NULL* + so an object allocation function can write ``return PyErr_NoMemory();`` when it + runs out of memory. + + +.. c:function:: PyObject* PyErr_SetFromErrno(PyObject *type) + + .. index:: single: strerror() + + This is a convenience function to raise an exception when a C library function + has returned an error and set the C variable :c:data:`errno`. It constructs a + tuple object whose first item is the integer :c:data:`errno` value and whose + second item is the corresponding error message (gotten from :c:func:`strerror`), + and then calls ``PyErr_SetObject(type, object)``. On Unix, when the + :c:data:`errno` value is :const:`EINTR`, indicating an interrupted system call, + this calls :c:func:`PyErr_CheckSignals`, and if that set the error indicator, + leaves it set to that. The function always returns *NULL*, so a wrapper + function around a system call can write ``return PyErr_SetFromErrno(type);`` + when the system call returns an error. + + +.. c:function:: PyObject* PyErr_SetFromErrnoWithFilenameObject(PyObject *type, PyObject *filenameObject) + + Similar to :c:func:`PyErr_SetFromErrno`, with the additional behavior that if + *filenameObject* is not *NULL*, it is passed to the constructor of *type* as + a third parameter. In the case of exceptions such as :exc:`IOError` and + :exc:`OSError`, this is used to define the :attr:`filename` attribute of the + exception instance. + + +.. c:function:: PyObject* PyErr_SetFromErrnoWithFilename(PyObject *type, const char *filename) + + Similar to :c:func:`PyErr_SetFromErrnoWithFilenameObject`, but the filename + is given as a C string. + + +.. c:function:: PyObject* PyErr_SetFromWindowsErr(int ierr) + + This is a convenience function to raise :exc:`WindowsError`. If called with + *ierr* of :c:data:`0`, the error code returned by a call to :c:func:`GetLastError` + is used instead. It calls the Win32 function :c:func:`FormatMessage` to retrieve + the Windows description of error code given by *ierr* or :c:func:`GetLastError`, + then it constructs a tuple object whose first item is the *ierr* value and whose + second item is the corresponding error message (gotten from + :c:func:`FormatMessage`), and then calls ``PyErr_SetObject(PyExc_WindowsError, + object)``. This function always returns *NULL*. Availability: Windows. + + +.. c:function:: PyObject* PyErr_SetExcFromWindowsErr(PyObject *type, int ierr) + + Similar to :c:func:`PyErr_SetFromWindowsErr`, with an additional parameter + specifying the exception type to be raised. Availability: Windows. + + .. versionadded:: 2.3 + + +.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilenameObject(int ierr, PyObject *filenameObject) + + Similar to :c:func:`PyErr_SetFromWindowsErr`, with the additional behavior that + if *filenameObject* is not *NULL*, it is passed to the constructor of + :exc:`WindowsError` as a third parameter. Availability: Windows. + + +.. c:function:: PyObject* PyErr_SetFromWindowsErrWithFilename(int ierr, const char *filename) + + Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, but the + filename is given as a C string. Availability: Windows. + + +.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilenameObject(PyObject *type, int ierr, PyObject *filename) + + Similar to :c:func:`PyErr_SetFromWindowsErrWithFilenameObject`, with an + additional parameter specifying the exception type to be raised. + Availability: Windows. + + .. versionadded:: 2.3 + + +.. c:function:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, const char *filename) + + Similar to :c:func:`PyErr_SetFromWindowsErrWithFilename`, with an additional + parameter specifying the exception type to be raised. Availability: Windows. + + .. versionadded:: 2.3 + + +.. c:function:: void PyErr_BadInternalCall() + + This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``, + where *message* indicates that an internal operation (e.g. a Python/C API + function) was invoked with an illegal argument. It is mostly for internal + use. + + +.. c:function:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel) + + Issue a warning message. The *category* argument is a warning category (see + below) or *NULL*; the *message* argument is a message string. *stacklevel* is a + positive number giving a number of stack frames; the warning will be issued from + the currently executing line of code in that stack frame. A *stacklevel* of 1 + is the function calling :c:func:`PyErr_WarnEx`, 2 is the function above that, + and so forth. + + This function normally prints a warning message to *sys.stderr*; however, it is + also possible that the user has specified that warnings are to be turned into + errors, and in that case this will raise an exception. It is also possible that + the function raises an exception because of a problem with the warning machinery + (the implementation imports the :mod:`warnings` module to do the heavy lifting). + The return value is ``0`` if no exception is raised, or ``-1`` if an exception + is raised. (It is not possible to determine whether a warning message is + actually printed, nor what the reason is for the exception; this is + intentional.) If an exception is raised, the caller should do its normal + exception handling (for example, :c:func:`Py_DECREF` owned references and return + an error value). + + Warning categories must be subclasses of :c:data:`Warning`; the default warning + category is :c:data:`RuntimeWarning`. The standard Python warning categories are + available as global variables whose names are ``PyExc_`` followed by the Python + exception name. These have the type :c:type:`PyObject\*`; they are all class + objects. Their names are :c:data:`PyExc_Warning`, :c:data:`PyExc_UserWarning`, + :c:data:`PyExc_UnicodeWarning`, :c:data:`PyExc_DeprecationWarning`, + :c:data:`PyExc_SyntaxWarning`, :c:data:`PyExc_RuntimeWarning`, and + :c:data:`PyExc_FutureWarning`. :c:data:`PyExc_Warning` is a subclass of + :c:data:`PyExc_Exception`; the other warning categories are subclasses of + :c:data:`PyExc_Warning`. + + For information about warning control, see the documentation for the + :mod:`warnings` module and the :option:`-W` option in the command line + documentation. There is no C API for warning control. + + +.. c:function:: int PyErr_Warn(PyObject *category, char *message) + + Issue a warning message. The *category* argument is a warning category (see + below) or *NULL*; the *message* argument is a message string. The warning will + appear to be issued from the function calling :c:func:`PyErr_Warn`, equivalent to + calling :c:func:`PyErr_WarnEx` with a *stacklevel* of 1. + + Deprecated; use :c:func:`PyErr_WarnEx` instead. + + +.. c:function:: int PyErr_WarnExplicit(PyObject *category, const char *message, const char *filename, int lineno, const char *module, PyObject *registry) + + Issue a warning message with explicit control over all warning attributes. This + is a straightforward wrapper around the Python function + :func:`warnings.warn_explicit`, see there for more information. The *module* + and *registry* arguments may be set to *NULL* to get the default effect + described there. + + +.. c:function:: int PyErr_WarnPy3k(char *message, int stacklevel) + + Issue a :exc:`DeprecationWarning` with the given *message* and *stacklevel* + if the :c:data:`Py_Py3kWarningFlag` flag is enabled. + + .. versionadded:: 2.6 + + +.. c:function:: int PyErr_CheckSignals() + + .. index:: + module: signal + single: SIGINT + single: KeyboardInterrupt (built-in exception) + + This function interacts with Python's signal handling. It checks whether a + signal has been sent to the processes and if so, invokes the corresponding + signal handler. If the :mod:`signal` module is supported, this can invoke a + signal handler written in Python. In all cases, the default effect for + :const:`SIGINT` is to raise the :exc:`KeyboardInterrupt` exception. If an + exception is raised the error indicator is set and the function returns ``-1``; + otherwise the function returns ``0``. The error indicator may or may not be + cleared if it was previously set. + + +.. c:function:: void PyErr_SetInterrupt() + + .. index:: + single: SIGINT + single: KeyboardInterrupt (built-in exception) + + This function simulates the effect of a :const:`SIGINT` signal arriving --- the + next time :c:func:`PyErr_CheckSignals` is called, :exc:`KeyboardInterrupt` will + be raised. It may be called without holding the interpreter lock. + + .. % XXX This was described as obsolete, but is used in + .. % thread.interrupt_main() (used from IDLE), so it's still needed. + + +.. c:function:: int PySignal_SetWakeupFd(int fd) + + This utility function specifies a file descriptor to which a ``'\0'`` byte will + be written whenever a signal is received. It returns the previous such file + descriptor. The value ``-1`` disables the feature; this is the initial state. + This is equivalent to :func:`signal.set_wakeup_fd` in Python, but without any + error checking. *fd* should be a valid file descriptor. The function should + only be called from the main thread. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyErr_NewException(char *name, PyObject *base, PyObject *dict) + + This utility function creates and returns a new exception class. The *name* + argument must be the name of the new exception, a C string of the form + ``module.classname``. The *base* and *dict* arguments are normally *NULL*. + This creates a class object derived from :exc:`Exception` (accessible in C as + :c:data:`PyExc_Exception`). + + The :attr:`__module__` attribute of the new class is set to the first part (up + to the last dot) of the *name* argument, and the class name is set to the last + part (after the last dot). The *base* argument can be used to specify alternate + base classes; it can either be only one class or a tuple of classes. The *dict* + argument can be used to specify a dictionary of class variables and methods. + + +.. c:function:: PyObject* PyErr_NewExceptionWithDoc(char *name, char *doc, PyObject *base, PyObject *dict) + + Same as :c:func:`PyErr_NewException`, except that the new exception class can + easily be given a docstring: If *doc* is non-*NULL*, it will be used as the + docstring for the exception class. + + .. versionadded:: 2.7 + + +.. c:function:: void PyErr_WriteUnraisable(PyObject *obj) + + This utility function prints a warning message to ``sys.stderr`` when an + exception has been set but it is impossible for the interpreter to actually + raise the exception. It is used, for example, when an exception occurs in an + :meth:`__del__` method. + + The function is called with a single argument *obj* that identifies the context + in which the unraisable exception occurred. The repr of *obj* will be printed in + the warning message. + + +.. _unicodeexceptions: + +Unicode Exception Objects +========================= + +The following functions are used to create and modify Unicode exceptions from C. + +.. c:function:: PyObject* PyUnicodeDecodeError_Create(const char *encoding, const char *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason) + + Create a :class:`UnicodeDecodeError` object with the attributes *encoding*, + *object*, *length*, *start*, *end* and *reason*. + +.. c:function:: PyObject* PyUnicodeEncodeError_Create(const char *encoding, const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason) + + Create a :class:`UnicodeEncodeError` object with the attributes *encoding*, + *object*, *length*, *start*, *end* and *reason*. + +.. c:function:: PyObject* PyUnicodeTranslateError_Create(const Py_UNICODE *object, Py_ssize_t length, Py_ssize_t start, Py_ssize_t end, const char *reason) + + Create a :class:`UnicodeTranslateError` object with the attributes *object*, + *length*, *start*, *end* and *reason*. + +.. c:function:: PyObject* PyUnicodeDecodeError_GetEncoding(PyObject *exc) + PyObject* PyUnicodeEncodeError_GetEncoding(PyObject *exc) + + Return the *encoding* attribute of the given exception object. + +.. c:function:: PyObject* PyUnicodeDecodeError_GetObject(PyObject *exc) + PyObject* PyUnicodeEncodeError_GetObject(PyObject *exc) + PyObject* PyUnicodeTranslateError_GetObject(PyObject *exc) + + Return the *object* attribute of the given exception object. + +.. c:function:: int PyUnicodeDecodeError_GetStart(PyObject *exc, Py_ssize_t *start) + int PyUnicodeEncodeError_GetStart(PyObject *exc, Py_ssize_t *start) + int PyUnicodeTranslateError_GetStart(PyObject *exc, Py_ssize_t *start) + + Get the *start* attribute of the given exception object and place it into + *\*start*. *start* must not be *NULL*. Return ``0`` on success, ``-1`` on + failure. + +.. c:function:: int PyUnicodeDecodeError_SetStart(PyObject *exc, Py_ssize_t start) + int PyUnicodeEncodeError_SetStart(PyObject *exc, Py_ssize_t start) + int PyUnicodeTranslateError_SetStart(PyObject *exc, Py_ssize_t start) + + Set the *start* attribute of the given exception object to *start*. Return + ``0`` on success, ``-1`` on failure. + +.. c:function:: int PyUnicodeDecodeError_GetEnd(PyObject *exc, Py_ssize_t *end) + int PyUnicodeEncodeError_GetEnd(PyObject *exc, Py_ssize_t *end) + int PyUnicodeTranslateError_GetEnd(PyObject *exc, Py_ssize_t *end) + + Get the *end* attribute of the given exception object and place it into + *\*end*. *end* must not be *NULL*. Return ``0`` on success, ``-1`` on + failure. + +.. c:function:: int PyUnicodeDecodeError_SetEnd(PyObject *exc, Py_ssize_t end) + int PyUnicodeEncodeError_SetEnd(PyObject *exc, Py_ssize_t end) + int PyUnicodeTranslateError_SetEnd(PyObject *exc, Py_ssize_t end) + + Set the *end* attribute of the given exception object to *end*. Return ``0`` + on success, ``-1`` on failure. + +.. c:function:: PyObject* PyUnicodeDecodeError_GetReason(PyObject *exc) + PyObject* PyUnicodeEncodeError_GetReason(PyObject *exc) + PyObject* PyUnicodeTranslateError_GetReason(PyObject *exc) + + Return the *reason* attribute of the given exception object. + +.. c:function:: int PyUnicodeDecodeError_SetReason(PyObject *exc, const char *reason) + int PyUnicodeEncodeError_SetReason(PyObject *exc, const char *reason) + int PyUnicodeTranslateError_SetReason(PyObject *exc, const char *reason) + + Set the *reason* attribute of the given exception object to *reason*. Return + ``0`` on success, ``-1`` on failure. + + +Recursion Control +================= + +These two functions provide a way to perform safe recursive calls at the C +level, both in the core and in extension modules. They are needed if the +recursive code does not necessarily invoke Python code (which tracks its +recursion depth automatically). + +.. c:function:: int Py_EnterRecursiveCall(char *where) + + Marks a point where a recursive C-level call is about to be performed. + + If :const:`USE_STACKCHECK` is defined, this function checks if the OS + stack overflowed using :c:func:`PyOS_CheckStack`. In this is the case, it + sets a :exc:`MemoryError` and returns a nonzero value. + + The function then checks if the recursion limit is reached. If this is the + case, a :exc:`RuntimeError` is set and a nonzero value is returned. + Otherwise, zero is returned. + + *where* should be a string such as ``" in instance check"`` to be + concatenated to the :exc:`RuntimeError` message caused by the recursion depth + limit. + +.. c:function:: void Py_LeaveRecursiveCall() + + Ends a :c:func:`Py_EnterRecursiveCall`. Must be called once for each + *successful* invocation of :c:func:`Py_EnterRecursiveCall`. + + +.. _standardexceptions: + +Standard Exceptions +=================== + +All standard Python exceptions are available as global variables whose names are +``PyExc_`` followed by the Python exception name. These have the type +:c:type:`PyObject\*`; they are all class objects. For completeness, here are all +the variables: + ++-------------------------------------+----------------------------+----------+ +| C Name | Python Name | Notes | ++=====================================+============================+==========+ +| :c:data:`PyExc_BaseException` | :exc:`BaseException` | (1), (4) | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_Exception` | :exc:`Exception` | \(1) | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_StandardError` | :exc:`StandardError` | \(1) | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_ArithmeticError` | :exc:`ArithmeticError` | \(1) | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_LookupError` | :exc:`LookupError` | \(1) | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_AssertionError` | :exc:`AssertionError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_AttributeError` | :exc:`AttributeError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_EOFError` | :exc:`EOFError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_EnvironmentError` | :exc:`EnvironmentError` | \(1) | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_FloatingPointError` | :exc:`FloatingPointError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_IOError` | :exc:`IOError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_ImportError` | :exc:`ImportError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_IndexError` | :exc:`IndexError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_KeyError` | :exc:`KeyError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_KeyboardInterrupt` | :exc:`KeyboardInterrupt` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_MemoryError` | :exc:`MemoryError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_NameError` | :exc:`NameError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_NotImplementedError` | :exc:`NotImplementedError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_OSError` | :exc:`OSError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_OverflowError` | :exc:`OverflowError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_ReferenceError` | :exc:`ReferenceError` | \(2) | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_RuntimeError` | :exc:`RuntimeError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_SyntaxError` | :exc:`SyntaxError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_SystemError` | :exc:`SystemError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_SystemExit` | :exc:`SystemExit` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_TypeError` | :exc:`TypeError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_ValueError` | :exc:`ValueError` | | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_WindowsError` | :exc:`WindowsError` | \(3) | ++-------------------------------------+----------------------------+----------+ +| :c:data:`PyExc_ZeroDivisionError` | :exc:`ZeroDivisionError` | | ++-------------------------------------+----------------------------+----------+ + +.. index:: + single: PyExc_BaseException + single: PyExc_Exception + single: PyExc_StandardError + single: PyExc_ArithmeticError + single: PyExc_LookupError + single: PyExc_AssertionError + single: PyExc_AttributeError + single: PyExc_EOFError + single: PyExc_EnvironmentError + single: PyExc_FloatingPointError + single: PyExc_IOError + single: PyExc_ImportError + single: PyExc_IndexError + single: PyExc_KeyError + single: PyExc_KeyboardInterrupt + single: PyExc_MemoryError + single: PyExc_NameError + single: PyExc_NotImplementedError + single: PyExc_OSError + single: PyExc_OverflowError + single: PyExc_ReferenceError + single: PyExc_RuntimeError + single: PyExc_SyntaxError + single: PyExc_SystemError + single: PyExc_SystemExit + single: PyExc_TypeError + single: PyExc_ValueError + single: PyExc_WindowsError + single: PyExc_ZeroDivisionError + +Notes: + +(1) + This is a base class for other standard exceptions. + +(2) + This is the same as :exc:`weakref.ReferenceError`. + +(3) + Only defined on Windows; protect code that uses this by testing that the + preprocessor macro ``MS_WINDOWS`` is defined. + +(4) + .. versionadded:: 2.5 + + +String Exceptions +================= + +.. versionchanged:: 2.6 + All exceptions to be raised or caught must be derived from :exc:`BaseException`. + Trying to raise a string exception now raises :exc:`TypeError`. +
diff --git a/Python-2.7.5/Doc/c-api/file.rst b/Python-2.7.5/Doc/c-api/file.rst new file mode 100644 index 0000000..20a7a60 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/file.rst
@@ -0,0 +1,179 @@ +.. highlightlang:: c + +.. _fileobjects: + +File Objects +------------ + +.. index:: object: file + +Python's built-in file objects are implemented entirely on the :c:type:`FILE\*` +support from the C standard library. This is an implementation detail and may +change in future releases of Python. + + +.. c:type:: PyFileObject + + This subtype of :c:type:`PyObject` represents a Python file object. + + +.. c:var:: PyTypeObject PyFile_Type + + .. index:: single: FileType (in module types) + + This instance of :c:type:`PyTypeObject` represents the Python file type. This is + exposed to Python programs as ``file`` and ``types.FileType``. + + +.. c:function:: int PyFile_Check(PyObject *p) + + Return true if its argument is a :c:type:`PyFileObject` or a subtype of + :c:type:`PyFileObject`. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. c:function:: int PyFile_CheckExact(PyObject *p) + + Return true if its argument is a :c:type:`PyFileObject`, but not a subtype of + :c:type:`PyFileObject`. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyFile_FromString(char *filename, char *mode) + + .. index:: single: fopen() + + On success, return a new file object that is opened on the file given by + *filename*, with a file mode given by *mode*, where *mode* has the same + semantics as the standard C routine :c:func:`fopen`. On failure, return *NULL*. + + +.. c:function:: PyObject* PyFile_FromFile(FILE *fp, char *name, char *mode, int (*close)(FILE*)) + + Create a new :c:type:`PyFileObject` from the already-open standard C file + pointer, *fp*. The function *close* will be called when the file should be + closed. Return *NULL* and close the file using *close* on failure. + *close* is optional and can be set to *NULL*. + + +.. c:function:: FILE* PyFile_AsFile(PyObject \*p) + + Return the file object associated with *p* as a :c:type:`FILE\*`. + + If the caller will ever use the returned :c:type:`FILE\*` object while + the :term:`GIL` is released it must also call the :c:func:`PyFile_IncUseCount` and + :c:func:`PyFile_DecUseCount` functions described below as appropriate. + + +.. c:function:: void PyFile_IncUseCount(PyFileObject \*p) + + Increments the PyFileObject's internal use count to indicate + that the underlying :c:type:`FILE\*` is being used. + This prevents Python from calling f_close() on it from another thread. + Callers of this must call :c:func:`PyFile_DecUseCount` when they are + finished with the :c:type:`FILE\*`. Otherwise the file object will + never be closed by Python. + + The :term:`GIL` must be held while calling this function. + + The suggested use is to call this after :c:func:`PyFile_AsFile` and before + you release the GIL:: + + FILE *fp = PyFile_AsFile(p); + PyFile_IncUseCount(p); + /* ... */ + Py_BEGIN_ALLOW_THREADS + do_something(fp); + Py_END_ALLOW_THREADS + /* ... */ + PyFile_DecUseCount(p); + + .. versionadded:: 2.6 + + +.. c:function:: void PyFile_DecUseCount(PyFileObject \*p) + + Decrements the PyFileObject's internal unlocked_count member to + indicate that the caller is done with its own use of the :c:type:`FILE\*`. + This may only be called to undo a prior call to :c:func:`PyFile_IncUseCount`. + + The :term:`GIL` must be held while calling this function (see the example + above). + + .. versionadded:: 2.6 + + +.. 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:`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:: PyObject* PyFile_Name(PyObject *p) + + Return the name of the file specified by *p* as a string object. + + +.. c:function:: void PyFile_SetBufSize(PyFileObject *p, int n) + + .. index:: single: setvbuf() + + Available on systems with :c:func:`setvbuf` only. This should only be called + immediately after file object creation. + + +.. c:function:: int PyFile_SetEncoding(PyFileObject *p, const char *enc) + + Set the file's encoding for Unicode output to *enc*. Return 1 on success and 0 + on failure. + + .. versionadded:: 2.3 + + +.. c:function:: int PyFile_SetEncodingAndErrors(PyFileObject *p, const char *enc, *errors) + + Set the file's encoding for Unicode output to *enc*, and its error + mode to *err*. Return 1 on success and 0 on failure. + + .. versionadded:: 2.6 + + +.. c:function:: int PyFile_SoftSpace(PyObject *p, int newflag) + + .. index:: single: softspace (file attribute) + + This function exists for internal use by the interpreter. Set the + :attr:`softspace` attribute of *p* to *newflag* and return the previous value. + *p* does not have to be a file object for this function to work properly; any + object is supported (thought its only interesting if the :attr:`softspace` + attribute can be set). This function clears any errors, and will return ``0`` + as the previous value if the attribute either does not exist or if there were + errors in retrieving it. There is no way to detect errors from this function, + but doing so should not be needed. + + +.. 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.
diff --git a/Python-2.7.5/Doc/c-api/float.rst b/Python-2.7.5/Doc/c-api/float.rst new file mode 100644 index 0000000..3aa7d18 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/float.rst
@@ -0,0 +1,120 @@ +.. 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 + + .. index:: single: FloatType (in modules types) + + This instance of :c:type:`PyTypeObject` represents the Python floating point + type. This is the same object as ``float`` and ``types.FloatType``. + + +.. c:function:: int PyFloat_Check(PyObject *p) + + Return true if its argument is a :c:type:`PyFloatObject` or a subtype of + :c:type:`PyFloatObject`. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. 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`. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyFloat_FromString(PyObject *str, char **pend) + + Create a :c:type:`PyFloatObject` object based on the string value in *str*, or + *NULL* on failure. The *pend* argument is ignored. It remains only for + backward compatibility. + + +.. 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`. + + .. versionadded:: 2.6 + + +.. c:function:: double PyFloat_GetMax() + + Return the maximum representable finite float *DBL_MAX* as C :c:type:`double`. + + .. versionadded:: 2.6 + + +.. c:function:: double PyFloat_GetMin() + + Return the minimum normalized positive float *DBL_MIN* as C :c:type:`double`. + + .. versionadded:: 2.6 + + +.. c:function:: int PyFloat_ClearFreeList() + + Clear the float free list. Return the number of items that could not + be freed. + + .. versionadded:: 2.6 + + +.. c:function:: void PyFloat_AsString(char *buf, PyFloatObject *v) + + Convert the argument *v* to a string, using the same rules as + :func:`str`. The length of *buf* should be at least 100. + + This function is unsafe to call because it writes to a buffer whose + length it does not know. + + .. deprecated:: 2.7 + Use :func:`PyObject_Str` or :func:`PyOS_double_to_string` instead. + + +.. c:function:: void PyFloat_AsReprString(char *buf, PyFloatObject *v) + + Same as PyFloat_AsString, except uses the same rules as + :func:`repr`. The length of *buf* should be at least 100. + + This function is unsafe to call because it writes to a buffer whose + length it does not know. + + .. deprecated:: 2.7 + Use :func:`PyObject_Repr` or :func:`PyOS_double_to_string` instead.
diff --git a/Python-2.7.5/Doc/c-api/function.rst b/Python-2.7.5/Doc/c-api/function.rst new file mode 100644 index 0000000..66f8675 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/function.rst
@@ -0,0 +1,83 @@ +.. 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, name and *__module__* are retrieved from the code + object, the argument defaults and closure are set to *NULL*. + + +.. 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.
diff --git a/Python-2.7.5/Doc/c-api/gcsupport.rst b/Python-2.7.5/Doc/c-api/gcsupport.rst new file mode 100644 index 0000000..2a4fda4 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/gcsupport.rst
@@ -0,0 +1,165 @@ +.. 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. + +.. An example showing the use of these interfaces can be found in "Supporting the +.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)". + +To create a container type, the :attr:`tp_flags` field of the type object must +include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the +:attr:`tp_traverse` handler. If instances of the type are mutable, a +:attr:`tp_clear` implementation must also be provided. + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *newsize*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. 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 :attr:`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. + +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 + (:attr:`tp_dealloc` handler) should call this for the object before any of + the fields used by the :attr:`tp_traverse` handler become invalid. + + +.. c:function:: void _PyObject_GC_UNTRACK(PyObject *op) + + A macro version of :c:func:`PyObject_GC_UnTrack`. It should not be used for + extension modules. + +The :attr:`tp_traverse` handler accepts a function parameter of this type: + + +.. c:type:: int (*visitproc)(PyObject *object, void *arg) + + Type of the visitor function passed to the :attr:`tp_traverse` handler. + The function should be called with an object to traverse as *object* and + the third parameter to the :attr:`tp_traverse` handler as *arg*. The + Python core uses several visitor functions to implement cyclic garbage + detection; it's not expected that users will need to write their own + visitor functions. + +The :attr:`tp_traverse` handler must have the following type: + + +.. 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 :attr:`tp_traverse` handlers, a :c:func:`Py_VISIT` macro is +provided. In order to use this macro, the :attr:`tp_traverse` implementation +must name its arguments exactly *visit* and *arg*: + + +.. c:function:: void Py_VISIT(PyObject *o) + + Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns + a non-zero value, then return it. Using this macro, :attr:`tp_traverse` + handlers look like:: + + static int + my_traverse(Noddy *self, visitproc visit, void *arg) + { + Py_VISIT(self->foo); + Py_VISIT(self->bar); + return 0; + } + + .. versionadded:: 2.4 + +The :attr:`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.
diff --git a/Python-2.7.5/Doc/c-api/gen.rst b/Python-2.7.5/Doc/c-api/gen.rst new file mode 100644 index 0000000..33cd27a --- /dev/null +++ b/Python-2.7.5/Doc/c-api/gen.rst
@@ -0,0 +1,38 @@ +.. 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`. + + +.. 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(ob) + + Return true if *ob* is a generator object; *ob* must not be *NULL*. + + +.. c:function:: int PyGen_CheckExact(ob) + + Return true if *ob*'s type is *PyGen_Type* is a generator object; *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 parameter must not be + *NULL*.
diff --git a/Python-2.7.5/Doc/c-api/import.rst b/Python-2.7.5/Doc/c-api/import.rst new file mode 100644 index 0000000..6f5678c --- /dev/null +++ b/Python-2.7.5/Doc/c-api/import.rst
@@ -0,0 +1,276 @@ +.. 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. Before Python 2.4, + the module may still be created in the failure case --- examine ``sys.modules`` + to find out. Starting with Python 2.4, a failing import of a module no longer + leaves the module in ``sys.modules``. + + .. versionchanged:: 2.4 + Failing imports remove incomplete module objects. + + .. versionchanged:: 2.6 + Always uses absolute imports. + + +.. c:function:: PyObject* PyImport_ImportModuleNoBlock(const char *name) + + This version of :c:func:`PyImport_ImportModule` does not block. It's intended + to be used in C functions that import other modules to execute a function. + The import may block if another thread holds the import lock. The function + :c:func:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch + the module from sys.modules and falls back to :c:func:`PyImport_ImportModule` + unless the lock is held, in which case the function will raise an + :exc:`ImportError`. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyImport_ImportModuleEx(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__`, 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 (before Python 2.4, the module may + still be created in this case). 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. + + .. versionchanged:: 2.4 + Failing imports remove incomplete module objects. + + .. versionchanged:: 2.6 + The function is an alias for :c:func:`PyImport_ImportModuleLevel` with + -1 as level, meaning relative import. + + +.. c:function:: PyObject* PyImport_ImportModuleLevel(char *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:: 2.5 + + +.. c:function:: PyObject* PyImport_Import(PyObject *name) + + .. index:: + module: rexec + module: ihooks + + This is a higher-level interface that calls the current "import hook function". + 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, e.g. by :mod:`rexec` or :mod:`ihooks`. + + .. versionchanged:: 2.6 + Always uses absolute imports. + + +.. c:function:: PyObject* PyImport_ReloadModule(PyObject *m) + + .. index:: builtin: reload + + Reload a module. This is best described by referring to the built-in Python + function :func:`reload`, as the standard :func:`reload` function calls this + function directly. 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_AddModule(const char *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. + + +.. c:function:: PyObject* PyImport_ExecCodeModule(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. Before Python 2.4, the + module could still be created in error cases. Starting with Python 2.4, *name* + is removed from :attr:`sys.modules` in error cases, and 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:`__file__` attribute will be set to the code object's + :c:member:`co_filename`. + + 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. + + .. versionchanged:: 2.4 + *name* is removed from :attr:`sys.modules` in error cases. + + +.. c:function:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, 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``. + + +.. c:function:: long PyImport_GetMagicNumber() + + Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and + :file:`.pyo` files). The magic number should be present in the first four bytes + of the bytecode file, in little-endian byte order. + + +.. 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 an importer 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 it should fall back to the built-in import mechanism. + Cache the result in :data:`sys.path_importer_cache`. Return a new reference + to the importer object. + + .. versionadded:: 2.6 + + +.. 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:: PyObject* _PyImport_FixupExtension(char *, char *) + + For internal use only. + + +.. c:function:: int PyImport_ImportFrozenModule(char *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.) + + +.. 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:: 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, void (*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. 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; + void (*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`.
diff --git a/Python-2.7.5/Doc/c-api/index.rst b/Python-2.7.5/Doc/c-api/index.rst new file mode 100644 index 0000000..2ce7b98 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/index.rst
@@ -0,0 +1,24 @@ +.. _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 + veryhigh.rst + refcounting.rst + exceptions.rst + utilities.rst + abstract.rst + concrete.rst + init.rst + memory.rst + objimpl.rst
diff --git a/Python-2.7.5/Doc/c-api/init.rst b/Python-2.7.5/Doc/c-api/init.rst new file mode 100644 index 0000000..6c58c5d --- /dev/null +++ b/Python-2.7.5/Doc/c-api/init.rst
@@ -0,0 +1,1145 @@ +.. highlightlang:: c + + +.. _initialization: + +***************************************** +Initialization, Finalization, and Threads +***************************************** + + +Initializing and finalizing the interpreter +=========================================== + + +.. c:function:: void Py_Initialize() + + .. index:: + single: Py_SetProgramName() + single: PyEval_InitThreads() + single: PyEval_ReleaseLock() + single: PyEval_AcquireLock() + single: modules (in module sys) + single: path (in module sys) + module: __builtin__ + module: __main__ + module: sys + triple: module; search; path + single: PySys_SetArgv() + single: PySys_SetArgvEx() + single: Py_Finalize() + + Initialize the Python interpreter. In an application embedding Python, this + should be called before using any other Python/C API functions; with the + exception of :c:func:`Py_SetProgramName`, :c:func:`Py_SetPythonHome`, :c:func:`PyEval_InitThreads`, + :c:func:`PyEval_ReleaseLock`, and :c:func:`PyEval_AcquireLock`. This initializes + the table of loaded modules (``sys.modules``), and creates the fundamental + modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. It also initializes + the module search path (``sys.path``). It does not set ``sys.argv``; use + :c:func:`PySys_SetArgvEx` for that. This is a no-op when called for a second time + (without calling :c:func:`Py_Finalize` first). There is no return value; it is a + fatal error if the initialization fails. + + +.. c:function:: void Py_InitializeEx(int initsigs) + + This function works like :c:func:`Py_Initialize` if *initsigs* is 1. If + *initsigs* is 0, it skips initialization registration of signal handlers, which + might be useful when Python is embedded. + + .. versionadded:: 2.4 + + +.. c:function:: int Py_IsInitialized() + + Return true (nonzero) when the Python interpreter has been initialized, false + (zero) if not. After :c:func:`Py_Finalize` is called, this returns false until + :c:func:`Py_Initialize` is called again. + + +.. c:function:: void Py_Finalize() + + Undo all initializations made by :c:func:`Py_Initialize` and subsequent use of + Python/C API functions, and destroy all sub-interpreters (see + :c:func:`Py_NewInterpreter` below) that were created and not yet destroyed since + the last call to :c:func:`Py_Initialize`. Ideally, this frees all memory + allocated by the Python interpreter. This is a no-op when called for a second + time (without calling :c:func:`Py_Initialize` again first). There is no return + value; errors during finalization are ignored. + + This function is provided for a number of reasons. An embedding application + might want to restart Python without having to restart the application itself. + An application that has loaded the Python interpreter from a dynamically + loadable library (or DLL) might want to free all memory allocated by Python + before unloading the DLL. During a hunt for memory leaks in an application a + developer might want to free all memory allocated by Python before exiting from + the application. + + **Bugs and caveats:** The destruction of modules and objects in modules is done + in random order; this may cause destructors (:meth:`__del__` methods) to fail + when they depend on other objects (even functions) or modules. Dynamically + loaded extension modules loaded by Python are not unloaded. Small amounts of + memory allocated by the Python interpreter may not be freed (if you find a leak, + please report it). Memory tied up in circular references between objects is not + freed. Some memory allocated by extension modules may not be freed. Some + extensions may not work properly if their initialization routine is called more + than once; this can happen if an application calls :c:func:`Py_Initialize` and + :c:func:`Py_Finalize` more than once. + + +Process-wide parameters +======================= + + +.. c:function:: void Py_SetProgramName(char *name) + + .. index:: + single: Py_Initialize() + single: main() + single: Py_GetPath() + + This function should be called before :c:func:`Py_Initialize` is called for + the first time, if it is called at all. It tells the interpreter the value + of the ``argv[0]`` argument to the :c:func:`main` function of the program. + This is used by :c:func:`Py_GetPath` and some other functions below to find + the Python run-time libraries relative to the interpreter executable. The + default value is ``'python'``. The argument should point to a + zero-terminated character string in static storage whose contents will not + change for the duration of the program's execution. No code in the Python + interpreter will change the contents of this storage. + + +.. c:function:: char* Py_GetProgramName() + + .. index:: single: Py_SetProgramName() + + Return the program name set with :c:func:`Py_SetProgramName`, or the default. + The returned string points into static storage; the caller should not modify its + value. + + +.. c:function:: char* Py_GetPrefix() + + Return the *prefix* for installed platform-independent files. This is derived + through a number of complicated rules from the program name set with + :c:func:`Py_SetProgramName` and some environment variables; for example, if the + program name is ``'/usr/local/bin/python'``, the prefix is ``'/usr/local'``. The + returned string points into static storage; the caller should not modify its + value. This corresponds to the :makevar:`prefix` variable in the top-level + :file:`Makefile` and the ``--prefix`` argument to the :program:`configure` + script at build time. The value is available to Python code as ``sys.prefix``. + It is only useful on Unix. See also the next function. + + +.. c:function:: char* Py_GetExecPrefix() + + Return the *exec-prefix* for installed platform-*dependent* files. This is + derived through a number of complicated rules from the program name set with + :c:func:`Py_SetProgramName` and some environment variables; for example, if the + program name is ``'/usr/local/bin/python'``, the exec-prefix is + ``'/usr/local'``. The returned string points into static storage; the caller + should not modify its value. This corresponds to the :makevar:`exec_prefix` + variable in the top-level :file:`Makefile` and the ``--exec-prefix`` + argument to the :program:`configure` script at build time. The value is + available to Python code as ``sys.exec_prefix``. It is only useful on Unix. + + Background: The exec-prefix differs from the prefix when platform dependent + files (such as executables and shared libraries) are installed in a different + directory tree. In a typical installation, platform dependent files may be + installed in the :file:`/usr/local/plat` subtree while platform independent may + be installed in :file:`/usr/local`. + + Generally speaking, a platform is a combination of hardware and software + families, e.g. Sparc machines running the Solaris 2.x operating system are + considered the same platform, but Intel machines running Solaris 2.x are another + platform, and Intel machines running Linux are yet another platform. Different + major revisions of the same operating system generally also form different + platforms. Non-Unix operating systems are a different story; the installation + strategies on those systems are so different that the prefix and exec-prefix are + meaningless, and set to the empty string. Note that compiled Python bytecode + files are platform independent (but not independent from the Python version by + which they were compiled!). + + System administrators will know how to configure the :program:`mount` or + :program:`automount` programs to share :file:`/usr/local` between platforms + while having :file:`/usr/local/plat` be a different filesystem for each + platform. + + +.. c:function:: char* Py_GetProgramFullPath() + + .. index:: + single: Py_SetProgramName() + single: executable (in module sys) + + Return the full program name of the Python executable; this is computed as a + side-effect of deriving the default module search path from the program name + (set by :c:func:`Py_SetProgramName` above). The returned string points into + static storage; the caller should not modify its value. The value is available + to Python code as ``sys.executable``. + + +.. c:function:: char* Py_GetPath() + + .. index:: + triple: module; search; path + single: path (in module sys) + + Return the default module search path; this is computed from the program name + (set by :c:func:`Py_SetProgramName` above) and some environment variables. + The returned string consists of a series of directory names separated by a + platform dependent delimiter character. The delimiter character is ``':'`` + on Unix and Mac OS X, ``';'`` on Windows. The returned string points into + static storage; the caller should not modify its value. The list + :data:`sys.path` is initialized with this value on interpreter startup; it + can be (and usually is) modified later to change the search path for loading + modules. + + .. XXX should give the exact rules + + +.. c:function:: const char* Py_GetVersion() + + Return the version of this Python interpreter. This is a string that looks + something like :: + + "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]" + + .. index:: single: version (in module sys) + + The first word (up to the first space character) is the current Python version; + the first three characters are the major and minor version separated by a + period. The returned string points into static storage; the caller should not + modify its value. The value is available to Python code as ``sys.version``. + + +.. c:function:: const char* Py_GetPlatform() + + .. index:: single: platform (in module sys) + + Return the platform identifier for the current platform. On Unix, this is + formed from the "official" name of the operating system, converted to lower + case, followed by the major revision number; e.g., for Solaris 2.x, which is + also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, it is + ``'darwin'``. On Windows, it is ``'win'``. The returned string points into + static storage; the caller should not modify its value. The value is available + to Python code as ``sys.platform``. + + +.. c:function:: const char* Py_GetCopyright() + + Return the official copyright string for the current Python version, for example + + ``'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'`` + + .. index:: single: copyright (in module sys) + + The returned string points into static storage; the caller should not modify its + value. The value is available to Python code as ``sys.copyright``. + + +.. c:function:: const char* Py_GetCompiler() + + Return an indication of the compiler used to build the current Python version, + in square brackets, for example:: + + "[GCC 2.7.2.2]" + + .. index:: single: version (in module sys) + + The returned string points into static storage; the caller should not modify its + value. The value is available to Python code as part of the variable + ``sys.version``. + + +.. c:function:: const char* Py_GetBuildInfo() + + Return information about the sequence number and build date and time of the + current Python interpreter instance, for example :: + + "#67, Aug 1 1997, 22:34:28" + + .. index:: single: version (in module sys) + + The returned string points into static storage; the caller should not modify its + value. The value is available to Python code as part of the variable + ``sys.version``. + + +.. c:function:: void PySys_SetArgvEx(int argc, char **argv, int updatepath) + + .. index:: + single: main() + single: Py_FatalError() + single: argv (in module sys) + + Set :data:`sys.argv` based on *argc* and *argv*. These parameters are + similar to those passed to the program's :c:func:`main` function with the + difference that the first entry should refer to the script file to be + executed rather than the executable hosting the Python interpreter. If there + isn't a script that will be run, the first entry in *argv* can be an empty + string. If this function fails to initialize :data:`sys.argv`, a fatal + condition is signalled using :c:func:`Py_FatalError`. + + If *updatepath* is zero, this is all the function does. If *updatepath* + is non-zero, the function also modifies :data:`sys.path` according to the + following algorithm: + + - If the name of an existing script is passed in ``argv[0]``, the absolute + path of the directory where the script is located is prepended to + :data:`sys.path`. + - Otherwise (that is, if *argc* is 0 or ``argv[0]`` doesn't point + to an existing file name), an empty string is prepended to + :data:`sys.path`, which is the same as prepending the current working + directory (``"."``). + + .. note:: + It is recommended that applications embedding the Python interpreter + for purposes other than executing a single script pass 0 as *updatepath*, + and update :data:`sys.path` themselves if desired. + See `CVE-2008-5983 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_. + + On versions before 2.6.6, you can achieve the same effect by manually + popping the first :data:`sys.path` element after having called + :c:func:`PySys_SetArgv`, for example using:: + + PyRun_SimpleString("import sys; sys.path.pop(0)\n"); + + .. versionadded:: 2.6.6 + + .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params; + check w/ Guido. + + +.. c:function:: void PySys_SetArgv(int argc, char **argv) + + This function works like :c:func:`PySys_SetArgvEx` with *updatepath* set to 1. + + +.. c:function:: void Py_SetPythonHome(char *home) + + Set the default "home" directory, that is, the location of the standard + Python libraries. See :envvar:`PYTHONHOME` for the meaning of the + argument string. + + The argument should point to a zero-terminated character string in static + storage whose contents will not change for the duration of the program's + execution. No code in the Python interpreter will change the contents of + this storage. + + +.. c:function:: char* Py_GetPythonHome() + + Return the default "home", that is, the value set by a previous call to + :c:func:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME` + environment variable if it is set. + + +.. _threads: + +Thread State and the Global Interpreter Lock +============================================ + +.. index:: + single: GIL + single: global interpreter lock + single: interpreter lock + single: lock, interpreter + +The Python interpreter is not fully thread-safe. In order to support +multi-threaded Python programs, there's a global lock, called the :term:`global +interpreter lock` or :term:`GIL`, that must be held by the current thread before +it can safely access Python objects. Without the lock, even the simplest +operations could cause problems in a multi-threaded program: for example, when +two threads simultaneously increment the reference count of the same object, the +reference count could end up being incremented only once instead of twice. + +.. index:: single: setcheckinterval() (in module sys) + +Therefore, the rule exists that only the thread that has acquired the +:term:`GIL` may operate on Python objects or call Python/C API functions. +In order to emulate concurrency of execution, the interpreter regularly +tries to switch threads (see :func:`sys.setcheckinterval`). The lock is also +released around potentially blocking I/O operations like reading or writing +a file, so that other Python threads can run in the meantime. + +.. index:: + single: PyThreadState + single: PyThreadState + +The Python interpreter keeps some thread-specific bookkeeping information +inside a data structure called :c:type:`PyThreadState`. There's also one +global variable pointing to the current :c:type:`PyThreadState`: it can +be retrieved using :c:func:`PyThreadState_Get`. + +Releasing the GIL from extension code +------------------------------------- + +Most extension code manipulating the :term:`GIL` has the following simple +structure:: + + Save the thread state in a local variable. + Release the global interpreter lock. + ... Do some blocking I/O operation ... + Reacquire the global interpreter lock. + Restore the thread state from the local variable. + +This is so common that a pair of macros exists to simplify it:: + + Py_BEGIN_ALLOW_THREADS + ... Do some blocking I/O operation ... + Py_END_ALLOW_THREADS + +.. index:: + single: Py_BEGIN_ALLOW_THREADS + single: Py_END_ALLOW_THREADS + +The :c:macro:`Py_BEGIN_ALLOW_THREADS` macro opens a new block and declares a +hidden local variable; the :c:macro:`Py_END_ALLOW_THREADS` macro closes the +block. These two macros are still available when Python is compiled without +thread support (they simply have an empty expansion). + +When thread support is enabled, the block above expands to the following code:: + + PyThreadState *_save; + + _save = PyEval_SaveThread(); + ...Do some blocking I/O operation... + PyEval_RestoreThread(_save); + +.. index:: + single: PyEval_RestoreThread() + single: PyEval_SaveThread() + +Here is how these functions work: the global interpreter lock is used to protect the pointer to the +current thread state. When releasing the lock and saving the thread state, +the current thread state pointer must be retrieved before the lock is released +(since another thread could immediately acquire the lock and store its own thread +state in the global variable). Conversely, when acquiring the lock and restoring +the thread state, the lock must be acquired before storing the thread state +pointer. + +.. note:: + Calling system I/O functions is the most common use case for releasing + the GIL, but it can also be useful before calling long-running computations + which don't need access to Python objects, such as compression or + cryptographic functions operating over memory buffers. For example, the + standard :mod:`zlib` and :mod:`hashlib` modules release the GIL when + compressing or hashing data. + +Non-Python created threads +-------------------------- + +When threads are created using the dedicated Python APIs (such as the +:mod:`threading` module), a thread state is automatically associated to them +and the code showed above is therefore correct. However, when threads are +created from C (for example by a third-party library with its own thread +management), they don't hold the GIL, nor is there a thread state structure +for them. + +If you need to call Python code from these threads (often this will be part +of a callback API provided by the aforementioned third-party library), +you must first register these threads with the interpreter by +creating a thread state data structure, then acquiring the GIL, and finally +storing their thread state pointer, before you can start using the Python/C +API. When you are done, you should reset the thread state pointer, release +the GIL, and finally free the thread state data structure. + +The :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` functions do +all of the above automatically. The typical idiom for calling into Python +from a C thread is:: + + PyGILState_STATE gstate; + gstate = PyGILState_Ensure(); + + /* Perform Python actions here. */ + result = CallSomeFunction(); + /* evaluate result or handle exception */ + + /* Release the thread. No Python API allowed beyond this point. */ + PyGILState_Release(gstate); + +Note that the :c:func:`PyGILState_\*` functions assume there is only one global +interpreter (created automatically by :c:func:`Py_Initialize`). Python +supports the creation of additional interpreters (using +:c:func:`Py_NewInterpreter`), but mixing multiple interpreters and the +:c:func:`PyGILState_\*` API is unsupported. + +Another important thing to note about threads is their behaviour in the face +of the C :c:func:`fork` call. On most systems with :c:func:`fork`, after a +process forks only the thread that issued the fork will exist. That also +means any locks held by other threads will never be released. Python solves +this for :func:`os.fork` by acquiring the locks it uses internally before +the fork, and releasing them afterwards. In addition, it resets any +:ref:`lock-objects` in the child. When extending or embedding Python, there +is no way to inform Python of additional (non-Python) locks that need to be +acquired before or reset after a fork. OS facilities such as +:c:func:`pthread_atfork` would need to be used to accomplish the same thing. +Additionally, when extending or embedding Python, calling :c:func:`fork` +directly rather than through :func:`os.fork` (and returning to or calling +into Python) may result in a deadlock by one of Python's internal locks +being held by a thread that is defunct after the fork. +:c:func:`PyOS_AfterFork` tries to reset the necessary locks, but is not +always able to. + + +High-level API +-------------- + +These are the most commonly used types and functions when writing C extension +code, or when embedding the Python interpreter: + +.. c:type:: PyInterpreterState + + This data structure represents the state shared by a number of cooperating + threads. Threads belonging to the same interpreter share their module + administration and a few other internal items. There are no public members in + this structure. + + Threads belonging to different interpreters initially share nothing, except + process state like available memory, open file descriptors and such. The global + interpreter lock is also shared by all threads, regardless of to which + interpreter they belong. + + +.. c:type:: PyThreadState + + This data structure represents the state of a single thread. The only public + data member is :c:type:`PyInterpreterState \*`:attr:`interp`, which points to + this thread's interpreter state. + + +.. c:function:: void PyEval_InitThreads() + + .. index:: + single: PyEval_ReleaseLock() + single: PyEval_ReleaseThread() + single: PyEval_SaveThread() + single: PyEval_RestoreThread() + + Initialize and acquire the global interpreter lock. It should be called in the + main thread before creating a second thread or engaging in any other thread + operations such as :c:func:`PyEval_ReleaseLock` or + ``PyEval_ReleaseThread(tstate)``. It is not needed before calling + :c:func:`PyEval_SaveThread` or :c:func:`PyEval_RestoreThread`. + + .. index:: single: Py_Initialize() + + This is a no-op when called for a second time. It is safe to call this function + before calling :c:func:`Py_Initialize`. + + .. index:: module: thread + + .. note:: + When only the main thread exists, no GIL operations are needed. This is a + common situation (most Python programs do not use threads), and the lock + operations slow the interpreter down a bit. Therefore, the lock is not + created initially. This situation is equivalent to having acquired the lock: + when there is only a single thread, all object accesses are safe. Therefore, + when this function initializes the global interpreter lock, it also acquires + it. Before the Python :mod:`_thread` module creates a new thread, knowing + that either it has the lock or the lock hasn't been created yet, it calls + :c:func:`PyEval_InitThreads`. When this call returns, it is guaranteed that + the lock has been created and that the calling thread has acquired it. + + It is **not** safe to call this function when it is unknown which thread (if + any) currently has the global interpreter lock. + + This function is not available when thread support is disabled at compile time. + + +.. c:function:: int PyEval_ThreadsInitialized() + + Returns a non-zero value if :c:func:`PyEval_InitThreads` has been called. This + function can be called without holding the GIL, and therefore can be used to + avoid calls to the locking API when running single-threaded. This function is + not available when thread support is disabled at compile time. + + .. versionadded:: 2.4 + + +.. c:function:: PyThreadState* PyEval_SaveThread() + + Release the global interpreter lock (if it has been created and thread + support is enabled) and reset the thread state to *NULL*, returning the + previous thread state (which is not *NULL*). If the lock has been created, + the current thread must have acquired it. (This function is available even + when thread support is disabled at compile time.) + + +.. c:function:: void PyEval_RestoreThread(PyThreadState *tstate) + + Acquire the global interpreter lock (if it has been created and thread + support is enabled) and set the thread state to *tstate*, which must not be + *NULL*. If the lock has been created, the current thread must not have + acquired it, otherwise deadlock ensues. (This function is available even + when thread support is disabled at compile time.) + + +.. c:function:: PyThreadState* PyThreadState_Get() + + Return the current thread state. The global interpreter lock must be held. + When the current thread state is *NULL*, this issues a fatal error (so that + the caller needn't check for *NULL*). + + +.. c:function:: PyThreadState* PyThreadState_Swap(PyThreadState *tstate) + + Swap the current thread state with the thread state given by the argument + *tstate*, which may be *NULL*. The global interpreter lock must be held + and is not released. + + +.. c:function:: void PyEval_ReInitThreads() + + This function is called from :c:func:`PyOS_AfterFork` to ensure that newly + created child processes don't hold locks referring to threads which + are not running in the child process. + + +The following functions use thread-local storage, and are not compatible +with sub-interpreters: + +.. c:function:: PyGILState_STATE PyGILState_Ensure() + + Ensure that the current thread is ready to call the Python C API regardless + of the current state of Python, or of the global interpreter lock. This may + be called as many times as desired by a thread as long as each call is + matched with a call to :c:func:`PyGILState_Release`. In general, other + thread-related APIs may be used between :c:func:`PyGILState_Ensure` and + :c:func:`PyGILState_Release` calls as long as the thread state is restored to + its previous state before the Release(). For example, normal usage of the + :c:macro:`Py_BEGIN_ALLOW_THREADS` and :c:macro:`Py_END_ALLOW_THREADS` macros is + acceptable. + + The return value is an opaque "handle" to the thread state when + :c:func:`PyGILState_Ensure` was called, and must be passed to + :c:func:`PyGILState_Release` to ensure Python is left in the same state. Even + though recursive calls are allowed, these handles *cannot* be shared - each + unique call to :c:func:`PyGILState_Ensure` must save the handle for its call + to :c:func:`PyGILState_Release`. + + When the function returns, the current thread will hold the GIL and be able + to call arbitrary Python code. Failure is a fatal error. + + .. versionadded:: 2.3 + + +.. c:function:: void PyGILState_Release(PyGILState_STATE) + + Release any resources previously acquired. After this call, Python's state will + be the same as it was prior to the corresponding :c:func:`PyGILState_Ensure` call + (but generally this state will be unknown to the caller, hence the use of the + GILState API). + + Every call to :c:func:`PyGILState_Ensure` must be matched by a call to + :c:func:`PyGILState_Release` on the same thread. + + .. versionadded:: 2.3 + + +.. c:function:: PyThreadState PyGILState_GetThisThreadState() + + Get the current thread state for this thread. May return ``NULL`` if no + GILState API has been used on the current thread. Note that the main thread + always has such a thread-state, even if no auto-thread-state call has been + made on the main thread. This is mainly a helper/diagnostic function. + + .. versionadded:: 2.3 + + +The following macros are normally used without a trailing semicolon; look for +example usage in the Python source distribution. + + +.. c:macro:: Py_BEGIN_ALLOW_THREADS + + This macro expands to ``{ PyThreadState *_save; _save = PyEval_SaveThread();``. + Note that it contains an opening brace; it must be matched with a following + :c:macro:`Py_END_ALLOW_THREADS` macro. See above for further discussion of this + macro. It is a no-op when thread support is disabled at compile time. + + +.. c:macro:: Py_END_ALLOW_THREADS + + This macro expands to ``PyEval_RestoreThread(_save); }``. Note that it contains + a closing brace; it must be matched with an earlier + :c:macro:`Py_BEGIN_ALLOW_THREADS` macro. See above for further discussion of + this macro. It is a no-op when thread support is disabled at compile time. + + +.. c:macro:: Py_BLOCK_THREADS + + This macro expands to ``PyEval_RestoreThread(_save);``: it is equivalent to + :c:macro:`Py_END_ALLOW_THREADS` without the closing brace. It is a no-op when + thread support is disabled at compile time. + + +.. c:macro:: Py_UNBLOCK_THREADS + + This macro expands to ``_save = PyEval_SaveThread();``: it is equivalent to + :c:macro:`Py_BEGIN_ALLOW_THREADS` without the opening brace and variable + declaration. It is a no-op when thread support is disabled at compile time. + + +Low-level API +------------- + +All of the following functions are only available when thread support is enabled +at compile time, and must be called only when the global interpreter lock has +been created. + + +.. c:function:: PyInterpreterState* PyInterpreterState_New() + + Create a new interpreter state object. The global interpreter lock need not + be held, but may be held if it is necessary to serialize calls to this + function. + + +.. c:function:: void PyInterpreterState_Clear(PyInterpreterState *interp) + + Reset all information in an interpreter state object. The global interpreter + lock must be held. + + +.. c:function:: void PyInterpreterState_Delete(PyInterpreterState *interp) + + Destroy an interpreter state object. The global interpreter lock need not be + held. The interpreter state must have been reset with a previous call to + :c:func:`PyInterpreterState_Clear`. + + +.. c:function:: PyThreadState* PyThreadState_New(PyInterpreterState *interp) + + Create a new thread state object belonging to the given interpreter object. + The global interpreter lock need not be held, but may be held if it is + necessary to serialize calls to this function. + + +.. c:function:: void PyThreadState_Clear(PyThreadState *tstate) + + Reset all information in a thread state object. The global interpreter lock + must be held. + + +.. c:function:: void PyThreadState_Delete(PyThreadState *tstate) + + Destroy a thread state object. The global interpreter lock need not be held. + The thread state must have been reset with a previous call to + :c:func:`PyThreadState_Clear`. + + +.. c:function:: PyObject* PyThreadState_GetDict() + + Return a dictionary in which extensions can store thread-specific state + information. Each extension should use a unique key to use to store state in + the dictionary. It is okay to call this function when no current thread state + is available. If this function returns *NULL*, no exception has been raised and + the caller should assume no current thread state is available. + + .. versionchanged:: 2.3 + Previously this could only be called when a current thread is active, and *NULL* + meant that an exception was raised. + + +.. c:function:: int PyThreadState_SetAsyncExc(long id, PyObject *exc) + + Asynchronously raise an exception in a thread. The *id* argument is the thread + id of the target thread; *exc* is the exception object to be raised. This + function does not steal any references to *exc*. To prevent naive misuse, you + must write your own C extension to call this. Must be called with the GIL held. + Returns the number of thread states modified; this is normally one, but will be + zero if the thread id isn't found. If *exc* is :const:`NULL`, the pending + exception (if any) for the thread is cleared. This raises no exceptions. + + .. versionadded:: 2.3 + + +.. c:function:: void PyEval_AcquireThread(PyThreadState *tstate) + + Acquire the global interpreter lock and set the current thread state to + *tstate*, which should not be *NULL*. The lock must have been created earlier. + If this thread already has the lock, deadlock ensues. + + :c:func:`PyEval_RestoreThread` is a higher-level function which is always + available (even when thread support isn't enabled or when threads have + not been initialized). + + +.. c:function:: void PyEval_ReleaseThread(PyThreadState *tstate) + + Reset the current thread state to *NULL* and release the global interpreter + lock. The lock must have been created earlier and must be held by the current + thread. The *tstate* argument, which must not be *NULL*, is only used to check + that it represents the current thread state --- if it isn't, a fatal error is + reported. + + :c:func:`PyEval_SaveThread` is a higher-level function which is always + available (even when thread support isn't enabled or when threads have + not been initialized). + + +.. c:function:: void PyEval_AcquireLock() + + Acquire the global interpreter lock. The lock must have been created earlier. + If this thread already has the lock, a deadlock ensues. + + .. warning:: + This function does not change the current thread state. Please use + :c:func:`PyEval_RestoreThread` or :c:func:`PyEval_AcquireThread` + instead. + + +.. c:function:: void PyEval_ReleaseLock() + + Release the global interpreter lock. The lock must have been created earlier. + + .. warning:: + This function does not change the current thread state. Please use + :c:func:`PyEval_SaveThread` or :c:func:`PyEval_ReleaseThread` + instead. + + +Sub-interpreter support +======================= + +While in most uses, you will only embed a single Python interpreter, there +are cases where you need to create several independent interpreters in the +same process and perhaps even in the same thread. Sub-interpreters allow +you to do that. You can switch between sub-interpreters using the +:c:func:`PyThreadState_Swap` function. You can create and destroy them +using the following functions: + + +.. c:function:: PyThreadState* Py_NewInterpreter() + + .. index:: + module: builtins + module: __main__ + module: sys + single: stdout (in module sys) + single: stderr (in module sys) + single: stdin (in module sys) + + Create a new sub-interpreter. This is an (almost) totally separate environment + for the execution of Python code. In particular, the new interpreter has + separate, independent versions of all imported modules, including the + fundamental modules :mod:`builtins`, :mod:`__main__` and :mod:`sys`. The + table of loaded modules (``sys.modules``) and the module search path + (``sys.path``) are also separate. The new environment has no ``sys.argv`` + variable. It has new standard I/O stream file objects ``sys.stdin``, + ``sys.stdout`` and ``sys.stderr`` (however these refer to the same underlying + file descriptors). + + The return value points to the first thread state created in the new + sub-interpreter. This thread state is made in the current thread state. + Note that no actual thread is created; see the discussion of thread states + below. If creation of the new interpreter is unsuccessful, *NULL* is + returned; no exception is set since the exception state is stored in the + current thread state and there may not be a current thread state. (Like all + other Python/C API functions, the global interpreter lock must be held before + calling this function and is still held when it returns; however, unlike most + other Python/C API functions, there needn't be a current thread state on + entry.) + + .. index:: + single: Py_Finalize() + single: Py_Initialize() + + Extension modules are shared between (sub-)interpreters as follows: the first + time a particular extension is imported, it is initialized normally, and a + (shallow) copy of its module's dictionary is squirreled away. When the same + extension is imported by another (sub-)interpreter, a new module is initialized + and filled with the contents of this copy; the extension's ``init`` function is + not called. Note that this is different from what happens when an extension is + imported after the interpreter has been completely re-initialized by calling + :c:func:`Py_Finalize` and :c:func:`Py_Initialize`; in that case, the extension's + ``initmodule`` function *is* called again. + + .. index:: single: close() (in module os) + + +.. c:function:: void Py_EndInterpreter(PyThreadState *tstate) + + .. index:: single: Py_Finalize() + + Destroy the (sub-)interpreter represented by the given thread state. The given + thread state must be the current thread state. See the discussion of thread + states below. When the call returns, the current thread state is *NULL*. All + thread states associated with this interpreter are destroyed. (The global + interpreter lock must be held before calling this function and is still held + when it returns.) :c:func:`Py_Finalize` will destroy all sub-interpreters that + haven't been explicitly destroyed at that point. + + +Bugs and caveats +---------------- + +Because sub-interpreters (and the main interpreter) are part of the same +process, the insulation between them isn't perfect --- for example, using +low-level file operations like :func:`os.close` they can +(accidentally or maliciously) affect each other's open files. Because of the +way extensions are shared between (sub-)interpreters, some extensions may not +work properly; this is especially likely when the extension makes use of +(static) global variables, or when the extension manipulates its module's +dictionary after its initialization. It is possible to insert objects created +in one sub-interpreter into a namespace of another sub-interpreter; this should +be done with great care to avoid sharing user-defined functions, methods, +instances or classes between sub-interpreters, since import operations executed +by such objects may affect the wrong (sub-)interpreter's dictionary of loaded +modules. + +Also note that combining this functionality with :c:func:`PyGILState_\*` APIs +is delicate, because these APIs assume a bijection between Python thread states +and OS-level threads, an assumption broken by the presence of sub-interpreters. +It is highly recommended that you don't switch sub-interpreters between a pair +of matching :c:func:`PyGILState_Ensure` and :c:func:`PyGILState_Release` calls. +Furthermore, extensions (such as :mod:`ctypes`) using these APIs to allow calling +of Python code from non-Python created threads will probably be broken when using +sub-interpreters. + + +Asynchronous Notifications +========================== + +A mechanism is provided to make asynchronous notifications to the main +interpreter thread. These notifications take the form of a function +pointer and a void argument. + +.. index:: single: setcheckinterval() (in module sys) + +Every check interval, when the global interpreter lock is released and +reacquired, Python will also call any such provided functions. This can be used +for example by asynchronous IO handlers. The notification can be scheduled from +a worker thread and the actual call than made at the earliest convenience by the +main thread where it has possession of the global interpreter lock and can +perform any Python API calls. + +.. c:function:: int Py_AddPendingCall(int (*func)(void *), void *arg) + + .. index:: single: Py_AddPendingCall() + + Post a notification to the Python main thread. If successful, *func* will be + called with the argument *arg* at the earliest convenience. *func* will be + called having the global interpreter lock held and can thus use the full + Python API and can take any action such as setting object attributes to + signal IO completion. It must return 0 on success, or -1 signalling an + exception. The notification function won't be interrupted to perform another + asynchronous notification recursively, but it can still be interrupted to + switch threads if the global interpreter lock is released, for example, if it + calls back into Python code. + + This function returns 0 on success in which case the notification has been + scheduled. Otherwise, for example if the notification buffer is full, it + returns -1 without setting any exception. + + This function can be called on any thread, be it a Python thread or some + other system thread. If it is a Python thread, it doesn't matter if it holds + the global interpreter lock or not. + + .. versionadded:: 2.7 + + + +.. _profiling: + +Profiling and Tracing +===================== + +.. sectionauthor:: Fred L. Drake, Jr. <[email protected]> + + +The Python interpreter provides some low-level support for attaching profiling +and execution tracing facilities. These are used for profiling, debugging, and +coverage analysis tools. + +Starting with Python 2.2, the implementation of this facility was substantially +revised, and an interface from C was added. This C interface allows the +profiling or tracing code to avoid the overhead of calling through Python-level +callable objects, making a direct C function call instead. The essential +attributes of the facility have not changed; the interface allows trace +functions to be installed per-thread, and the basic events reported to the trace +function are the same as had been reported to the Python-level trace functions +in previous versions. + + +.. c:type:: int (*Py_tracefunc)(PyObject *obj, PyFrameObject *frame, int what, PyObject *arg) + + The type of the trace function registered using :c:func:`PyEval_SetProfile` and + :c:func:`PyEval_SetTrace`. The first parameter is the object passed to the + registration function as *obj*, *frame* is the frame object to which the event + pertains, *what* is one of the constants :const:`PyTrace_CALL`, + :const:`PyTrace_EXCEPTION`, :const:`PyTrace_LINE`, :const:`PyTrace_RETURN`, + :const:`PyTrace_C_CALL`, :const:`PyTrace_C_EXCEPTION`, or + :const:`PyTrace_C_RETURN`, and *arg* depends on the value of *what*: + + +------------------------------+--------------------------------------+ + | Value of *what* | Meaning of *arg* | + +==============================+======================================+ + | :const:`PyTrace_CALL` | Always *NULL*. | + +------------------------------+--------------------------------------+ + | :const:`PyTrace_EXCEPTION` | Exception information as returned by | + | | :func:`sys.exc_info`. | + +------------------------------+--------------------------------------+ + | :const:`PyTrace_LINE` | Always *NULL*. | + +------------------------------+--------------------------------------+ + | :const:`PyTrace_RETURN` | Value being returned to the caller, | + | | or *NULL* if caused by an exception. | + +------------------------------+--------------------------------------+ + | :const:`PyTrace_C_CALL` | Function object being called. | + +------------------------------+--------------------------------------+ + | :const:`PyTrace_C_EXCEPTION` | Function object being called. | + +------------------------------+--------------------------------------+ + | :const:`PyTrace_C_RETURN` | Function object being called. | + +------------------------------+--------------------------------------+ + + +.. c:var:: int PyTrace_CALL + + The value of the *what* parameter to a :c:type:`Py_tracefunc` function when a new + call to a function or method is being reported, or a new entry into a generator. + Note that the creation of the iterator for a generator function is not reported + as there is no control transfer to the Python bytecode in the corresponding + frame. + + +.. c:var:: int PyTrace_EXCEPTION + + The value of the *what* parameter to a :c:type:`Py_tracefunc` function when an + exception has been raised. The callback function is called with this value for + *what* when after any bytecode is processed after which the exception becomes + set within the frame being executed. The effect of this is that as exception + propagation causes the Python stack to unwind, the callback is called upon + return to each frame as the exception propagates. Only trace functions receives + these events; they are not needed by the profiler. + + +.. c:var:: int PyTrace_LINE + + The value passed as the *what* parameter to a trace function (but not a + profiling function) when a line-number event is being reported. + + +.. c:var:: int PyTrace_RETURN + + The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a + call is returning without propagating an exception. + + +.. c:var:: int PyTrace_C_CALL + + The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C + function is about to be called. + + +.. c:var:: int PyTrace_C_EXCEPTION + + The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C + function has raised an exception. + + +.. c:var:: int PyTrace_C_RETURN + + The value for the *what* parameter to :c:type:`Py_tracefunc` functions when a C + function has returned. + + +.. c:function:: void PyEval_SetProfile(Py_tracefunc func, PyObject *obj) + + Set the profiler function to *func*. The *obj* parameter is passed to the + function as its first parameter, and may be any Python object, or *NULL*. If + the profile function needs to maintain state, using a different value for *obj* + for each thread provides a convenient and thread-safe place to store it. The + profile function is called for all monitored events except the line-number + events. + + +.. c:function:: void PyEval_SetTrace(Py_tracefunc func, PyObject *obj) + + Set the tracing function to *func*. This is similar to + :c:func:`PyEval_SetProfile`, except the tracing function does receive line-number + events. + +.. c:function:: PyObject* PyEval_GetCallStats(PyObject *self) + + Return a tuple of function call counts. There are constants defined for the + positions within the tuple: + + +-------------------------------+-------+ + | Name | Value | + +===============================+=======+ + | :const:`PCALL_ALL` | 0 | + +-------------------------------+-------+ + | :const:`PCALL_FUNCTION` | 1 | + +-------------------------------+-------+ + | :const:`PCALL_FAST_FUNCTION` | 2 | + +-------------------------------+-------+ + | :const:`PCALL_FASTER_FUNCTION`| 3 | + +-------------------------------+-------+ + | :const:`PCALL_METHOD` | 4 | + +-------------------------------+-------+ + | :const:`PCALL_BOUND_METHOD` | 5 | + +-------------------------------+-------+ + | :const:`PCALL_CFUNCTION` | 6 | + +-------------------------------+-------+ + | :const:`PCALL_TYPE` | 7 | + +-------------------------------+-------+ + | :const:`PCALL_GENERATOR` | 8 | + +-------------------------------+-------+ + | :const:`PCALL_OTHER` | 9 | + +-------------------------------+-------+ + | :const:`PCALL_POP` | 10 | + +-------------------------------+-------+ + + :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created. + :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used. + + If there is a method call where the call can be optimized by changing + the argument tuple and calling the function directly, it gets recorded + twice. + + This function is only present if Python is compiled with :const:`CALL_PROFILE` + defined. + +.. _advanced-debugging: + +Advanced Debugger Support +========================= + +.. sectionauthor:: Fred L. Drake, Jr. <[email protected]> + + +These functions are only intended to be used by advanced debugging tools. + + +.. c:function:: PyInterpreterState* PyInterpreterState_Head() + + Return the interpreter state object at the head of the list of all such objects. + + .. versionadded:: 2.2 + + +.. c:function:: PyInterpreterState* PyInterpreterState_Next(PyInterpreterState *interp) + + Return the next interpreter state object after *interp* from the list of all + such objects. + + .. versionadded:: 2.2 + + +.. c:function:: PyThreadState * PyInterpreterState_ThreadHead(PyInterpreterState *interp) + + Return the a pointer to the first :c:type:`PyThreadState` object in the list of + threads associated with the interpreter *interp*. + + .. versionadded:: 2.2 + + +.. c:function:: PyThreadState* PyThreadState_Next(PyThreadState *tstate) + + Return the next thread state object after *tstate* from the list of all such + objects belonging to the same :c:type:`PyInterpreterState` object. + + .. versionadded:: 2.2 +
diff --git a/Python-2.7.5/Doc/c-api/int.rst b/Python-2.7.5/Doc/c-api/int.rst new file mode 100644 index 0000000..254219c --- /dev/null +++ b/Python-2.7.5/Doc/c-api/int.rst
@@ -0,0 +1,139 @@ +.. highlightlang:: c + +.. _intobjects: + +Plain Integer Objects +--------------------- + +.. index:: object: integer + + +.. c:type:: PyIntObject + + This subtype of :c:type:`PyObject` represents a Python integer object. + + +.. c:var:: PyTypeObject PyInt_Type + + .. index:: single: IntType (in modules types) + + This instance of :c:type:`PyTypeObject` represents the Python plain integer type. + This is the same object as ``int`` and ``types.IntType``. + + +.. c:function:: int PyInt_Check(PyObject *o) + + Return true if *o* is of type :c:data:`PyInt_Type` or a subtype of + :c:data:`PyInt_Type`. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. c:function:: int PyInt_CheckExact(PyObject *o) + + Return true if *o* is of type :c:data:`PyInt_Type`, but not a subtype of + :c:data:`PyInt_Type`. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyInt_FromString(char *str, char **pend, int base) + + Return a new :c:type:`PyIntObject` or :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``, the radix will be + determined based on the leading characters of *str*: if *str* starts with + ``'0x'`` or ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix + 8 will be used; otherwise radix 10 will be used. If *base* is not ``0``, it + must be between ``2`` and ``36``, inclusive. Leading spaces are ignored. If + there are no digits, :exc:`ValueError` will be raised. If the string represents + a number too large to be contained within the machine's :c:type:`long int` type + and overflow warnings are being suppressed, a :c:type:`PyLongObject` will be + returned. If overflow warnings are not being suppressed, *NULL* will be + returned in this case. + + +.. c:function:: PyObject* PyInt_FromLong(long ival) + + Create a new integer object with a value of *ival*. + + 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* PyInt_FromSsize_t(Py_ssize_t ival) + + Create a new integer object with a value of *ival*. If the value is larger + than ``LONG_MAX`` or smaller than ``LONG_MIN``, a long integer object is + returned. + + .. versionadded:: 2.5 + + +.. c:function:: PyObject* PyInt_FromSize_t(size_t ival) + + Create a new integer object with a value of *ival*. If the value exceeds + ``LONG_MAX``, a long integer object is returned. + + .. versionadded:: 2.5 + + +.. c:function:: long PyInt_AsLong(PyObject *io) + + Will first attempt to cast the object to a :c:type:`PyIntObject`, if it is not + already one, and then return its value. If there is an error, ``-1`` is + returned, and the caller should check ``PyErr_Occurred()`` to find out whether + there was an error, or whether the value just happened to be -1. + + +.. c:function:: long PyInt_AS_LONG(PyObject *io) + + Return the value of the object *io*. No error checking is performed. + + +.. c:function:: unsigned long PyInt_AsUnsignedLongMask(PyObject *io) + + Will first attempt to cast the object to a :c:type:`PyIntObject` or + :c:type:`PyLongObject`, if it is not already one, and then return its value as + unsigned long. This function does not check for overflow. + + .. versionadded:: 2.3 + + +.. c:function:: unsigned PY_LONG_LONG PyInt_AsUnsignedLongLongMask(PyObject *io) + + Will first attempt to cast the object to a :c:type:`PyIntObject` or + :c:type:`PyLongObject`, if it is not already one, and then return its value as + unsigned long long, without checking for overflow. + + .. versionadded:: 2.3 + + +.. c:function:: Py_ssize_t PyInt_AsSsize_t(PyObject *io) + + Will first attempt to cast the object to a :c:type:`PyIntObject` or + :c:type:`PyLongObject`, if it is not already one, and then return its value as + :c:type:`Py_ssize_t`. + + .. versionadded:: 2.5 + + +.. c:function:: long PyInt_GetMax() + + .. index:: single: LONG_MAX + + Return the system's idea of the largest integer it can handle + (:const:`LONG_MAX`, as defined in the system header files). + + +.. c:function:: int PyInt_ClearFreeList() + + Clear the integer free list. Return the number of items that could not + be freed. + + .. versionadded:: 2.6
diff --git a/Python-2.7.5/Doc/c-api/intro.rst b/Python-2.7.5/Doc/c-api/intro.rst new file mode 100644 index 0000000..6414277 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/intro.rst
@@ -0,0 +1,638 @@ +.. 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 ``sys.version[:3]``. 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, PyInt_FromLong(1L)); + PyTuple_SetItem(t, 1, PyInt_FromLong(2L)); + PyTuple_SetItem(t, 2, PyString_FromString("three")); + +Here, :c:func:`PyInt_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) + { + int i, n; + + n = PyObject_Length(target); + if (n < 0) + return -1; + for (i = 0; i < n; i++) { + PyObject *index = PyInt_FromLong(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) + { + int i, n; + long total = 0; + 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 (!PyInt_Check(item)) continue; /* Skip non-integers */ + total += PyInt_AsLong(item); + } + return total; + } + +.. index:: single: sum_list() + +:: + + long + sum_sequence(PyObject *sequence) + { + int i, n; + long total = 0; + 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 (PyInt_Check(item)) + total += PyInt_AsLong(item); + 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. + +.. index:: + single: exc_type (in module sys) + single: exc_value (in module sys) + single: exc_traceback (in module sys) + +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 objects +``sys.exc_type``, ``sys.exc_value``, and ``sys.exc_traceback``; 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_type`` 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 = PyInt_FromLong(0L); + if (item == NULL) + goto error; + } + const_one = PyInt_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: __builtin__ + module: __main__ + module: sys + module: exceptions + 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:`__builtin__`, :mod:`__main__`, :mod:`sys`, and :mod:`exceptions`. 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_Finalize`. 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_Finalize` +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 long 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. +
diff --git a/Python-2.7.5/Doc/c-api/iter.rst b/Python-2.7.5/Doc/c-api/iter.rst new file mode 100644 index 0000000..88ac0c1 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/iter.rst
@@ -0,0 +1,50 @@ +.. highlightlang:: c + +.. _iterator: + +Iterator Protocol +================= + +.. versionadded:: 2.2 + +There are only a couple of 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*. If the object is an iterator, + this retrieves the next value from the iteration, and returns *NULL* with no + exception set if there are no remaining items. If the object is not an + iterator, :exc:`TypeError` is raised, or if there is an error in 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 */ + }
diff --git a/Python-2.7.5/Doc/c-api/iterator.rst b/Python-2.7.5/Doc/c-api/iterator.rst new file mode 100644 index 0000000..3931bb9 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/iterator.rst
@@ -0,0 +1,62 @@ +.. 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. + + .. versionadded:: 2.2 + + +.. c:function:: int PySeqIter_Check(op) + + Return true if the type of *op* is :c:data:`PySeqIter_Type`. + + .. versionadded:: 2.2 + + +.. 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. + + .. versionadded:: 2.2 + + +.. 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. + + .. versionadded:: 2.2 + + +.. c:function:: int PyCallIter_Check(op) + + Return true if the type of *op* is :c:data:`PyCallIter_Type`. + + .. versionadded:: 2.2 + + +.. 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. + + .. versionadded:: 2.2
diff --git a/Python-2.7.5/Doc/c-api/list.rst b/Python-2.7.5/Doc/c-api/list.rst new file mode 100644 index 0000000..0aed0f3 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/list.rst
@@ -0,0 +1,189 @@ +.. 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 ``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. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. 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. + + .. versionadded:: 2.2 + + +.. 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`. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int`. This might require changes in + your code for properly supporting 64-bit systems. + + +.. c:function:: Py_ssize_t PyList_GET_SIZE(PyObject *list) + + Macro form of :c:func:`PyList_Size` without error checking. + + .. versionchanged:: 2.5 + This macro returned an :c:type:`int`. This might require changes in your + code for properly supporting 64-bit systems. + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` for *index*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i) + + Macro form of :c:func:`PyList_GetItem` without error checking. + + .. versionchanged:: 2.5 + This macro used an :c:type:`int` for *i*. This might require changes in + your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` for *index*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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 + it being replaced; any reference in *list* at position *i* will be + leaked. + + .. versionchanged:: 2.5 + This macro used an :c:type:`int` for *i*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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)``. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` for *index*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` for *low* and *high*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` for *low* and *high*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. 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)``.
diff --git a/Python-2.7.5/Doc/c-api/long.rst b/Python-2.7.5/Doc/c-api/long.rst new file mode 100644 index 0000000..5a8e51d --- /dev/null +++ b/Python-2.7.5/Doc/c-api/long.rst
@@ -0,0 +1,278 @@ +.. highlightlang:: c + +.. _longobjects: + +Long Integer Objects +-------------------- + +.. index:: object: long integer + + +.. c:type:: PyLongObject + + This subtype of :c:type:`PyObject` represents a Python long integer object. + + +.. c:var:: PyTypeObject PyLong_Type + + .. index:: single: LongType (in modules types) + + This instance of :c:type:`PyTypeObject` represents the Python long integer type. + This is the same object as ``long`` and ``types.LongType``. + + +.. c:function:: int PyLong_Check(PyObject *p) + + Return true if its argument is a :c:type:`PyLongObject` or a subtype of + :c:type:`PyLongObject`. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. 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`. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyLong_FromLong(long v) + + Return a new :c:type:`PyLongObject` object from *v*, or *NULL* on failure. + + +.. 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. + + .. versionadded:: 2.6 + + +.. 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. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyLong_FromSsize_t(Py_ssize_t v) + + Return a new :c:type:`PyLongObject` object with a value of *v*, or *NULL* + on failure. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyLong_FromSize_t(size_t v) + + Return a new :c:type:`PyLongObject` object with a value of *v*, or *NULL* + on failure. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyLong_FromLongLong(PY_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 PY_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(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``, the radix will be determined + based on the leading characters of *str*: if *str* starts with ``'0x'`` or + ``'0X'``, radix 16 will be used; if *str* starts with ``'0'``, radix 8 will be + used; otherwise radix 10 will be used. If *base* is not ``0``, it must be + between ``2`` and ``36``, inclusive. Leading spaces 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 long integer value. The first + parameter, *u*, points to the first character of the Unicode string, *length* + gives the number of characters, and *base* is the radix for the conversion. The + radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError` + will be raised. + + .. versionadded:: 1.6 + + .. versionchanged:: 2.5 + This function used an :c:type:`int` for *length*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyLong_FromVoidPtr(void *p) + + Create a Python integer or long integer from the pointer *p*. The pointer value + can be retrieved from the resulting value using :c:func:`PyLong_AsVoidPtr`. + + .. versionadded:: 1.5.2 + + .. versionchanged:: 2.5 + If the integer is larger than LONG_MAX, a positive long integer is returned. + + +.. c:function:: long PyLong_AsLong(PyObject *pylong) + + .. index:: + single: LONG_MAX + single: OverflowError (built-in exception) + + Return a C :c:type:`long` representation of the contents of *pylong*. If + *pylong* is greater than :const:`LONG_MAX`, an :exc:`OverflowError` is raised + and ``-1`` will be returned. + + +.. c:function:: long PyLong_AsLongAndOverflow(PyObject *pylong, int *overflow) + + Return a C :c:type:`long` representation of the contents of + *pylong*. If *pylong* 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 (for example a TypeError or + MemoryError), then ``-1`` will be returned and *\*overflow* will + be ``0``. + + .. versionadded:: 2.7 + + +.. c:function:: PY_LONG_LONG PyLong_AsLongLongAndOverflow(PyObject *pylong, int *overflow) + + Return a C :c:type:`long long` representation of the contents of + *pylong*. If *pylong* 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 (for example a TypeError or + MemoryError), then ``-1`` will be returned and *\*overflow* will + be ``0``. + + .. versionadded:: 2.7 + + +.. 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 the contents of *pylong*. If + *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is raised + and ``-1`` will be returned. + + .. versionadded:: 2.6 + + +.. 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 the contents of *pylong*. + If *pylong* is greater than :const:`ULONG_MAX`, an :exc:`OverflowError` is + raised. + + +.. c:function:: Py_ssize_t PyLong_AsSsize_t(PyObject *pylong) + + .. index:: + single: PY_SSIZE_T_MAX + + Return a :c:type:`Py_ssize_t` representation of the contents of *pylong*. If + *pylong* is greater than :const:`PY_SSIZE_T_MAX`, an :exc:`OverflowError` is + raised. + + .. versionadded:: 2.6 + + +.. c:function:: PY_LONG_LONG PyLong_AsLongLong(PyObject *pylong) + + .. index:: + single: OverflowError (built-in exception) + + Return a C :c:type:`long long` from a Python long integer. If + *pylong* cannot be represented as a :c:type:`long long`, an + :exc:`OverflowError` is raised and ``-1`` is returned. + + .. versionadded:: 2.2 + + +.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLong(PyObject *pylong) + + .. index:: + single: OverflowError (built-in exception) + + Return a C :c:type:`unsigned long long` from a Python long integer. If + *pylong* cannot be represented as an :c:type:`unsigned long long`, an + :exc:`OverflowError` is raised and ``(unsigned long long)-1`` is + returned. + + .. versionadded:: 2.2 + + .. versionchanged:: 2.7 + A negative *pylong* now raises :exc:`OverflowError`, not + :exc:`TypeError`. + + +.. c:function:: unsigned long PyLong_AsUnsignedLongMask(PyObject *io) + + Return a C :c:type:`unsigned long` from a Python long integer, without checking + for overflow. + + .. versionadded:: 2.3 + + +.. c:function:: unsigned PY_LONG_LONG PyLong_AsUnsignedLongLongMask(PyObject *io) + + Return a C :c:type:`unsigned long long` from a Python long integer, without + checking for overflow. + + .. versionadded:: 2.3 + + +.. c:function:: double PyLong_AsDouble(PyObject *pylong) + + Return a C :c:type:`double` representation of the contents of *pylong*. If + *pylong* cannot be approximately represented as a :c:type:`double`, an + :exc:`OverflowError` exception is raised and ``-1.0`` will be returned. + + +.. c:function:: void* PyLong_AsVoidPtr(PyObject *pylong) + + Convert a Python integer or long 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`. + + .. versionadded:: 1.5.2 + + .. versionchanged:: 2.5 + For values outside 0..LONG_MAX, both signed and unsigned integers are accepted. + +
diff --git a/Python-2.7.5/Doc/c-api/mapping.rst b/Python-2.7.5/Doc/c-api/mapping.rst new file mode 100644 index 0000000..7a83a50 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/mapping.rst
@@ -0,0 +1,83 @@ +.. highlightlang:: c + +.. _mapping: + +Mapping Protocol +================ + + +.. c:function:: int PyMapping_Check(PyObject *o) + + Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. 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. For + objects that do not provide mapping protocol, this is equivalent to the Python + expression ``len(o)``. + + .. versionchanged:: 2.5 + These functions returned an :c:type:`int` type. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: int PyMapping_DelItemString(PyObject *o, char *key) + + Remove the mapping for object *key* from the object *o*. Return ``-1`` on + failure. This is equivalent to the Python statement ``del o[key]``. + + +.. c:function:: int PyMapping_DelItem(PyObject *o, PyObject *key) + + Remove the mapping for object *key* from the object *o*. Return ``-1`` on + failure. This is equivalent to the Python statement ``del o[key]``. + + +.. c:function:: int PyMapping_HasKeyString(PyObject *o, char *key) + + On success, return ``1`` if the mapping object has the key *key* and ``0`` + otherwise. This is equivalent to ``o[key]``, returning ``True`` on success + and ``False`` on an exception. This function always succeeds. + + +.. 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 ``o[key]``, returning ``True`` on success and ``False`` + on an exception. This function always succeeds. + + +.. c:function:: PyObject* PyMapping_Keys(PyObject *o) + + On success, return a list of the keys in object *o*. On failure, return *NULL*. + This is equivalent to the Python expression ``o.keys()``. + + +.. c:function:: PyObject* PyMapping_Values(PyObject *o) + + On success, return a list of the values in object *o*. On failure, return + *NULL*. This is equivalent to the Python expression ``o.values()``. + + +.. c:function:: PyObject* PyMapping_Items(PyObject *o) + + On success, return a list of the items in object *o*, where each item is a tuple + containing a key-value pair. On failure, return *NULL*. This is equivalent to + the Python expression ``o.items()``. + + +.. c:function:: PyObject* PyMapping_GetItemString(PyObject *o, char *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 PyMapping_SetItemString(PyObject *o, char *key, PyObject *v) + + Map the object *key* to the value *v* in object *o*. Returns ``-1`` on failure. + This is the equivalent of the Python statement ``o[key] = v``.
diff --git a/Python-2.7.5/Doc/c-api/marshal.rst b/Python-2.7.5/Doc/c-api/marshal.rst new file mode 100644 index 0000000..b82cc96 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/marshal.rst
@@ -0,0 +1,100 @@ +.. 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 (new in Python 2.4) shares interned strings in +the file, and upon unmarshalling. Version 2 (new in Python 2.5) 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. + + .. versionchanged:: 2.4 + *version* indicates the file format. + + +.. c:function:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version) + + Marshal a Python object, *value*, to *file*. + + .. versionchanged:: 2.4 + *version* indicates the file format. + + +.. c:function:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version) + + Return a string object containing the marshalled representation of *value*. + + .. versionchanged:: 2.4 + *version* indicates the file format. + + +The following functions allow marshalled values to be read back in. + +XXX What about error detection? It appears that reading past the end of the +file will always result in a negative numeric value (where that's relevant), +but it's not clear that negative values won't be handled properly when there's +no error. What's the right way to tell? Should only non-negative values be +written using these routines? + + +.. 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`. + + +.. 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`. + + +.. 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` 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` or :exc:`TypeError`) and returns *NULL*. + + +.. c:function:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len) + + Return a Python object from the data stream in a character buffer + containing *len* bytes pointed to by *string*. On error, sets the + appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns + *NULL*. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *len*. This might require + changes in your code for properly supporting 64-bit systems.
diff --git a/Python-2.7.5/Doc/c-api/memory.rst b/Python-2.7.5/Doc/c-api/memory.rst new file mode 100644 index 0000000..5465571 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/memory.rst
@@ -0,0 +1,209 @@ +.. highlightlang:: c + + +.. _memory: + +***************** +Memory Management +***************** + +.. sectionauthor:: Vladimir Marangozov <[email protected]> + + + +.. _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 she regularly manipulates 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 = PyString_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. + + +.. _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: + + +.. 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_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` or :c:func:`PyMem_Realloc`. 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` or :c:func:`PyMem_Realloc`. 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. + +:c:func:`PyMem_MALLOC`, :c:func:`PyMem_REALLOC`, :c:func:`PyMem_FREE`. + +:c:func:`PyMem_NEW`, :c:func:`PyMem_RESIZE`, :c:func:`PyMem_DEL`. + + +.. _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 = PyString_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 = PyString_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. +
diff --git a/Python-2.7.5/Doc/c-api/method.rst b/Python-2.7.5/Doc/c-api/method.rst new file mode 100644 index 0000000..71ddeda --- /dev/null +++ b/Python-2.7.5/Doc/c-api/method.rst
@@ -0,0 +1,72 @@ +.. highlightlang:: c + +.. _method-objects: + +Method Objects +-------------- + +.. index:: object: method + +There are some useful functions that are useful for working with method objects. + + +.. 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, PyObject *class) + + Return a new method object, with *func* being any callable object; this is the + function that will be called when the method is called. If this method should + be bound to an instance, *self* should be the instance and *class* should be the + class of *self*, otherwise *self* should be *NULL* and *class* should be the + class which provides the unbound method.. + + +.. c:function:: PyObject* PyMethod_Class(PyObject *meth) + + Return the class object from which the method *meth* was created; if this was + created from an instance, it will be the class of the instance. + + +.. c:function:: PyObject* PyMethod_GET_CLASS(PyObject *meth) + + Macro version of :c:func:`PyMethod_Class` which avoids error checking. + + +.. 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* if it is bound, otherwise + return *NULL*. + + +.. 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. + + .. versionadded:: 2.6
diff --git a/Python-2.7.5/Doc/c-api/module.rst b/Python-2.7.5/Doc/c-api/module.rst new file mode 100644 index 0000000..56e63cf --- /dev/null +++ b/Python-2.7.5/Doc/c-api/module.rst
@@ -0,0 +1,121 @@ +.. highlightlang:: c + +.. _moduleobjects: + +Module Objects +-------------- + +.. index:: object: module + +There are only a few functions special to module objects. + + +.. 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. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. c:function:: int PyModule_CheckExact(PyObject *p) + + Return true if *p* is a module object, but not a subtype of + :c:data:`PyModule_Type`. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyModule_New(const char *name) + + .. index:: + single: __name__ (module attribute) + single: __doc__ (module attribute) + single: __file__ (module attribute) + + Return a new module object with the :attr:`__name__` attribute set to *name*. + Only the module's :attr:`__doc__` and :attr:`__name__` attributes are filled in; + the caller is responsible for providing a :attr:`__file__` attribute. + + +.. 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:`__dict__` attribute of the module object. This + function never fails. It is recommended extensions use other + :c:func:`PyModule_\*` and :c:func:`PyObject_\*` functions rather than directly + manipulate a module's :attr:`__dict__`. + + +.. c:function:: char* PyModule_GetName(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. + + +.. c:function:: char* PyModule_GetFilename(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 string, + raise :exc:`SystemError` and return *NULL*. + + +.. 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. + + .. versionadded:: 2.0 + + +.. 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. + + .. versionadded:: 2.0 + + +.. 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. + + .. versionadded:: 2.0 + +.. 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. + + .. versionadded:: 2.6 + +.. c:function:: int PyModule_AddStringMacro(PyObject *module, macro) + + Add a string constant to *module*. + + .. versionadded:: 2.6 +
diff --git a/Python-2.7.5/Doc/c-api/none.rst b/Python-2.7.5/Doc/c-api/none.rst new file mode 100644 index 0000000..aeaca97 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/none.rst
@@ -0,0 +1,28 @@ +.. 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. + + .. versionadded:: 2.4 +
diff --git a/Python-2.7.5/Doc/c-api/number.rst b/Python-2.7.5/Doc/c-api/number.rst new file mode 100644 index 0000000..75b7341 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/number.rst
@@ -0,0 +1,322 @@ +.. 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_Divide(PyObject *o1, PyObject *o2) + + Returns the result of dividing *o1* by *o2*, or *NULL* on failure. This is the + equivalent of the Python expression ``o1 / o2``. + + +.. 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. + + .. versionadded:: 2.2 + + +.. 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. + + .. versionadded:: 2.2 + + +.. 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_InPlaceDivide(PyObject *o1, PyObject *o2) + + Returns the result 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_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``. + + .. versionadded:: 2.2 + + +.. 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. + + .. versionadded:: 2.2 + + +.. 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:: int PyNumber_Coerce(PyObject **p1, PyObject **p2) + + .. index:: builtin: coerce + + This function takes the addresses of two variables of type :c:type:`PyObject\*`. + If the objects pointed to by ``*p1`` and ``*p2`` have the same type, increment + their reference count and return ``0`` (success). If the objects can be + converted to a common numeric type, replace ``*p1`` and ``*p2`` by their + converted value (with 'new' reference counts), and return ``0``. If no + conversion is possible, or if some other error occurs, return ``-1`` (failure) + and don't increment the reference counts. The call ``PyNumber_Coerce(&o1, + &o2)`` is equivalent to the Python statement ``o1, o2 = coerce(o1, o2)``. + + +.. c:function:: int PyNumber_CoerceEx(PyObject **p1, PyObject **p2) + + This function is similar to :c:func:`PyNumber_Coerce`, except that it returns + ``1`` when the conversion is not possible and when no error is raised. + Reference counts are still not increased in this case. + + +.. c:function:: PyObject* PyNumber_Int(PyObject *o) + + .. index:: builtin: int + + Returns the *o* converted to an integer object on success, or *NULL* on failure. + If the argument is outside the integer range a long object will be returned + instead. This is the equivalent of the Python expression ``int(o)``. + + +.. c:function:: PyObject* PyNumber_Long(PyObject *o) + + .. index:: builtin: long + + Returns the *o* converted to a long integer object on success, or *NULL* on + failure. This is the equivalent of the Python expression ``long(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 or long on success or *NULL* with a + :exc:`TypeError` exception raised on failure. + + .. versionadded:: 2.5 + + +.. c:function:: PyObject* PyNumber_ToBase(PyObject *n, int base) + + Returns the integer *n* converted to *base* as a string with a base + marker of ``'0b'``, ``'0o'``, or ``'0x'`` if applicable. When + *base* is not 2, 8, 10, or 16, the format is ``'x#num'`` where x is the + base. If *n* is not an int object, it is converted with + :c:func:`PyNumber_Index` first. + + .. versionadded:: 2.6 + + +.. 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 *o* can be converted to a Python int or long 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. + + .. versionadded:: 2.5 + + +.. c:function:: int PyIndex_Check(PyObject *o) + + Returns True if *o* is an index integer (has the nb_index slot of the + tp_as_number structure filled in). + + .. versionadded:: 2.5
diff --git a/Python-2.7.5/Doc/c-api/objbuffer.rst b/Python-2.7.5/Doc/c-api/objbuffer.rst new file mode 100644 index 0000000..c5228c6 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/objbuffer.rst
@@ -0,0 +1,66 @@ +.. highlightlang:: c + +.. _abstract-buffer: + + +Old Buffer Protocol +=================== + +This section describes the legacy buffer protocol, which has been introduced +in Python 1.6. It is still supported but deprecated in the Python 2.x series. +Python 3 introduces a new buffer protocol which fixes weaknesses and +shortcomings of the protocol, and has been backported to Python 2.6. See +:ref:`bufferobjects` for more information. + + +.. 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. + + .. versionadded:: 1.6 + + .. versionchanged:: 2.5 + This function used an :c:type:`int *` type for *buffer_len*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionadded:: 1.6 + + .. versionchanged:: 2.5 + This function used an :c:type:`int *` type for *buffer_len*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. c:function:: int PyObject_CheckReadBuffer(PyObject *o) + + Returns ``1`` if *o* supports the single-segment readable buffer interface. + Otherwise returns ``0``. + + .. versionadded:: 2.2 + + +.. c:function:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len) + + Returns a pointer to a writeable 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. + + .. versionadded:: 1.6 + + .. versionchanged:: 2.5 + This function used an :c:type:`int *` type for *buffer_len*. This might + require changes in your code for properly supporting 64-bit systems. +
diff --git a/Python-2.7.5/Doc/c-api/object.rst b/Python-2.7.5/Doc/c-api/object.rst new file mode 100644 index 0000000..a02326f --- /dev/null +++ b/Python-2.7.5/Doc/c-api/object.rst
@@ -0,0 +1,402 @@ +.. highlightlang:: c + +.. _object: + +Object Protocol +=============== + + +.. 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. + + +.. 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. + + +.. 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:`__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*. Returns ``-1`` on failure. This is the equivalent of the Python statement + ``o.attr_name = v``. + + +.. 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*. Returns ``-1`` on failure. This is the equivalent of the Python statement + ``o.attr_name = v``. + + +.. c:function:: int PyObject_GenericSetAttr(PyObject *o, PyObject *name, PyObject *value) + + Generic attribute setter function that is meant to be put into a type + object's ``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 the attribute in the instance dictionary. Otherwise, the + attribute is set in the object's :attr:`__dict__` (if present). 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_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:: int PyObject_Cmp(PyObject *o1, PyObject *o2, int *result) + + .. index:: builtin: cmp + + Compare the values of *o1* and *o2* using a routine provided by *o1*, if one + exists, otherwise with a routine provided by *o2*. The result of the comparison + is returned in *result*. Returns ``-1`` on failure. This is the equivalent of + the Python statement ``result = cmp(o1, o2)``. + + +.. c:function:: int PyObject_Compare(PyObject *o1, PyObject *o2) + + .. index:: builtin: cmp + + Compare the values of *o1* and *o2* using a routine provided by *o1*, if one + exists, otherwise with a routine provided by *o2*. Returns the result of the + comparison on success. On error, the value returned is undefined; use + :c:func:`PyErr_Occurred` to detect an error. This is equivalent to the Python + expression ``cmp(o1, o2)``. + + +.. 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 and + by reverse quotes. + + +.. c:function:: PyObject* PyObject_Str(PyObject *o) + + .. index:: builtin: str + + 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 + by the :keyword:`print` statement. + + +.. c:function:: PyObject* PyObject_Bytes(PyObject *o) + + .. index:: builtin: bytes + + Compute a bytes representation of object *o*. In 2.x, this is just a alias + for :c:func:`PyObject_Str`. + + +.. c:function:: PyObject* PyObject_Unicode(PyObject *o) + + .. index:: builtin: unicode + + Compute a Unicode string representation of object *o*. Returns the Unicode + string representation on success, *NULL* on failure. This is the equivalent of + the Python expression ``unicode(o)``. Called by the :func:`unicode` built-in + function. + + +.. c:function:: int PyObject_IsInstance(PyObject *inst, PyObject *cls) + + Returns ``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 type object rather than a class object, :c:func:`PyObject_IsInstance` + returns ``1`` if *inst* is of type *cls*. 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 *inst* is not a + class instance and *cls* is neither a type object, nor a class object, nor a + tuple, *inst* must have a :attr:`__class__` attribute --- the class relationship + of the value of that attribute with *cls* will be used to determine the result + of this function. + + .. versionadded:: 2.1 + + .. versionchanged:: 2.2 + Support for a tuple as the second argument added. + +Subclass determination is done in a fairly straightforward way, but includes a +wrinkle that implementors of extensions to the class system may want to be aware +of. If :class:`A` and :class:`B` are class objects, :class:`B` is a subclass of +:class:`A` if it inherits from :class:`A` either directly or indirectly. If +either is not a class object, a more general mechanism is used to determine the +class relationship of the two objects. When testing if *B* is a subclass of +*A*, if *A* is *B*, :c:func:`PyObject_IsSubclass` returns true. If *A* and *B* +are different objects, *B*'s :attr:`__bases__` attribute is searched in a +depth-first fashion for *A* --- the presence of the :attr:`__bases__` attribute +is considered sufficient for this determination. + + +.. c:function:: int PyObject_IsSubclass(PyObject *derived, PyObject *cls) + + Returns ``1`` if the class *derived* is identical to or derived from the class + *cls*, otherwise returns ``0``. In case of an error, returns ``-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 either *derived* or *cls* is not an actual class object (or tuple), + this function uses the generic algorithm described above. + + .. versionadded:: 2.1 + + .. versionchanged:: 2.3 + Older versions of Python did not support a tuple as the second argument. + + +.. 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) + + .. index:: builtin: apply + + 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 + ``apply(callable_object, args, kw)`` or ``callable_object(*args, **kw)``. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyObject_CallObject(PyObject *callable_object, PyObject *args) + + .. index:: builtin: apply + + 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 ``apply(callable_object, args)`` or + ``callable_object(*args)``. + + +.. c:function:: PyObject* PyObject_CallFunction(PyObject *callable, char *format, ...) + + .. index:: builtin: apply + + 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 ``apply(callable, args)`` or + ``callable(*args)``. Note that if you only pass :c:type:`PyObject \*` args, + :c:func:`PyObject_CallFunctionObjArgs` is a faster alternative. + + +.. c:function:: PyObject* PyObject_CallMethod(PyObject *o, char *method, 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. + + +.. 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. + + .. versionadded:: 2.2 + + +.. 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. + + .. versionadded:: 2.2 + + +.. c:function:: long 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)``. + + +.. c:function:: long 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. + + .. versionadded:: 2.6 + + +.. 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*. + + .. versionadded:: 2.2 + + +.. c:function:: Py_ssize_t PyObject_Length(PyObject *o) + Py_ssize_t PyObject_Size(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)``. + + .. versionchanged:: 2.5 + These functions returned an :c:type:`int` type. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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*. Returns ``-1`` on failure. This is the + equivalent of the Python statement ``o[key] = v``. + + +.. c:function:: int PyObject_DelItem(PyObject *o, PyObject *key) + + Delete the mapping for *key* from *o*. Returns ``-1`` on failure. This is the + equivalent of the Python statement ``del o[key]``. + + +.. c:function:: int PyObject_AsFileDescriptor(PyObject *o) + + Derives a file descriptor from a Python object. If the object is an integer or + long integer, its value is returned. If not, the object's :meth:`fileno` method + is called if it exists; the method must return an integer or long integer, which + is returned as the file descriptor value. Returns ``-1`` on failure. + + +.. 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.
diff --git a/Python-2.7.5/Doc/c-api/objimpl.rst b/Python-2.7.5/Doc/c-api/objimpl.rst new file mode 100644 index 0000000..b335188 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/objimpl.rst
@@ -0,0 +1,18 @@ +.. 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
diff --git a/Python-2.7.5/Doc/c-api/refcounting.rst b/Python-2.7.5/Doc/c-api/refcounting.rst new file mode 100644 index 0000000..49675a8 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/refcounting.rst
@@ -0,0 +1,74 @@ +.. 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. + + .. versionadded:: 2.4 + +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`. +
diff --git a/Python-2.7.5/Doc/c-api/reflection.rst b/Python-2.7.5/Doc/c-api/reflection.rst new file mode 100644 index 0000000..59edbb3 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/reflection.rst
@@ -0,0 +1,55 @@ +.. 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:: int PyEval_GetRestricted() + + If there is a current frame and it is executing in restricted mode, return true, + otherwise false. + + +.. 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*.
diff --git a/Python-2.7.5/Doc/c-api/sequence.rst b/Python-2.7.5/Doc/c-api/sequence.rst new file mode 100644 index 0000000..2b668a5 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/sequence.rst
@@ -0,0 +1,218 @@ +.. highlightlang:: c + +.. _sequence: + +Sequence Protocol +================= + + +.. c:function:: int PySequence_Check(PyObject *o) + + Return ``1`` if the object provides sequence protocol, and ``0`` otherwise. + 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. + For objects that do not provide sequence protocol, this is equivalent to the + Python expression ``len(o)``. + + .. versionchanged:: 2.5 + These functions returned an :c:type:`int` type. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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``. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *count*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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``. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *count*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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]``. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *i*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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]``. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *i1* and *i2*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. c:function:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v) + + Assign object *v* to the *i*\ th element of *o*. Returns ``-1`` on failure. This + is the equivalent of the Python statement ``o[i] = v``. This function *does + not* steal a reference to *v*. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *i*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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]``. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *i*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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``. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *i1* and *i2*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. 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]``. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *i1* and *i2*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. 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)``. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. 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)``. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PySequence_List(PyObject *o) + + Return a list object with the same contents as the arbitrary sequence *o*. The + returned list is guaranteed to be new. + + +.. c:function:: PyObject* PySequence_Tuple(PyObject *o) + + .. index:: builtin: tuple + + Return a tuple object with the same contents as the arbitrary sequence *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) + + Returns the sequence *o* as a tuple, 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, raises :exc:`TypeError` with *m* as the message text. + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *i*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionadded:: 2.4 + + +.. 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. + + .. versionadded:: 2.3 + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *i*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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.
diff --git a/Python-2.7.5/Doc/c-api/set.rst b/Python-2.7.5/Doc/c-api/set.rst new file mode 100644 index 0000000..41c4af4 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/set.rst
@@ -0,0 +1,175 @@ +.. highlightlang:: c + +.. _setobjects: + +Set Objects +----------- + +.. sectionauthor:: Raymond D. Hettinger <[email protected]> + + +.. index:: + object: set + object: frozenset + +.. versionadded:: 2.5 + +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. + + .. versionadded:: 2.6 + +.. c:function:: int PyFrozenSet_Check(PyObject *p) + + Return true if *p* is a :class:`frozenset` object or an instance of a + subtype. + + .. versionadded:: 2.6 + +.. 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. + + .. versionchanged:: 2.6 + Now guaranteed to return a brand-new :class:`frozenset`. Formerly, + frozensets of zero-length were a singleton. This got in the way of + building-up new frozensets with :meth:`PySet_Add`. + +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. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int`. This might require changes in + your code for properly supporting 64-bit systems. + + +.. 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. Does not apply to :class:`frozenset` + instances. 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 an not an instance of :class:`set` or its + subtype. + + .. versionchanged:: 2.6 + Now works with instances of :class:`frozenset` or its subtypes. + Like :c:func:`PyTuple_SetItem` in that it can be used to fill-in the + values of brand new frozensets before they are exposed to other code. + +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:`discard` + method, this function does not automatically convert unhashable sets into + temporary frozensets. Raise :exc:`PyExc_SystemError` if *set* is an 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 an not an instance of + :class:`set` or its subtype. + + +.. c:function:: int PySet_Clear(PyObject *set) + + Empty an existing set of all elements.
diff --git a/Python-2.7.5/Doc/c-api/slice.rst b/Python-2.7.5/Doc/c-api/slice.rst new file mode 100644 index 0000000..f74230a --- /dev/null +++ b/Python-2.7.5/Doc/c-api/slice.rst
@@ -0,0 +1,68 @@ +.. highlightlang:: c + +.. _slice-objects: + +Slice Objects +------------- + + +.. c:var:: PyTypeObject PySlice_Type + + .. index:: single: SliceType (in module types) + + The type object for slice objects. This is the same as ``slice`` and + ``types.SliceType``. + + +.. 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(PySliceObject *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. If you want to use slice + objects in versions of Python prior to 2.3, you would probably do well to + incorporate the source of :c:func:`PySlice_GetIndicesEx`, suitably renamed, + in the source of your extension. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *length* and an + :c:type:`int *` type for *start*, *stop*, and *step*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: int PySlice_GetIndicesEx(PySliceObject *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. + + .. versionadded:: 2.3 + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *length* and an + :c:type:`int *` type for *start*, *stop*, *step*, and *slicelength*. This + might require changes in your code for properly supporting 64-bit + systems.
diff --git a/Python-2.7.5/Doc/c-api/string.rst b/Python-2.7.5/Doc/c-api/string.rst new file mode 100644 index 0000000..ecf7050 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/string.rst
@@ -0,0 +1,333 @@ +.. highlightlang:: c + +.. _stringobjects: + +String/Bytes Objects +-------------------- + +These functions raise :exc:`TypeError` when expecting a string parameter and are +called with a non-string parameter. + +.. note:: + + These functions have been renamed to PyBytes_* in Python 3.x. Unless + otherwise noted, the PyBytes functions available in 3.x are aliased to their + PyString_* equivalents to help porting. + +.. index:: object: string + + +.. c:type:: PyStringObject + + This subtype of :c:type:`PyObject` represents a Python string object. + + +.. c:var:: PyTypeObject PyString_Type + + .. index:: single: StringType (in module types) + + This instance of :c:type:`PyTypeObject` represents the Python string type; it is + the same object as ``str`` and ``types.StringType`` in the Python layer. . + + +.. c:function:: int PyString_Check(PyObject *o) + + Return true if the object *o* is a string object or an instance of a subtype of + the string type. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. c:function:: int PyString_CheckExact(PyObject *o) + + Return true if the object *o* is a string object, but not an instance of a + subtype of the string type. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyString_FromString(const char *v) + + Return a new string 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* PyString_FromStringAndSize(const char *v, Py_ssize_t len) + + Return a new string 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 + string are uninitialized. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *len*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyString_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 string and return a string + 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: + + .. % This should be exactly the same as the table in PyErr_Format. + .. % One should just refer to the other. + .. % 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. + .. % Similar comments apply to the %ll width modifier and + .. % PY_FORMAT_LONG_LONG. + .. % %u, %lu, %zu should have "new in Python 2.5" blurbs. + + +-------------------+---------------+--------------------------------+ + | Format Characters | Type | Comment | + +===================+===============+================================+ + | :attr:`%%` | *n/a* | The literal % character. | + +-------------------+---------------+--------------------------------+ + | :attr:`%c` | int | A single character, | + | | | represented as an 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:`%lld` | long long | Exactly equivalent to | + | | | ``printf("%lld")``. | + +-------------------+---------------+--------------------------------+ + | :attr:`%llu` | unsigned | Exactly equivalent to | + | | long long | ``printf("%llu")``. | + +-------------------+---------------+--------------------------------+ + | :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 string, and any extra arguments discarded. + + .. note:: + + The `"%lld"` and `"%llu"` format specifiers are only available + when :const:`HAVE_LONG_LONG` is defined. + + .. versionchanged:: 2.7 + Support for `"%lld"` and `"%llu"` added. + + +.. c:function:: PyObject* PyString_FromFormatV(const char *format, va_list vargs) + + Identical to :c:func:`PyString_FromFormat` except that it takes exactly two + arguments. + + +.. c:function:: Py_ssize_t PyString_Size(PyObject *string) + + Return the length of the string in string object *string*. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. c:function:: Py_ssize_t PyString_GET_SIZE(PyObject *string) + + Macro form of :c:func:`PyString_Size` but without error checking. + + .. versionchanged:: 2.5 + This macro returned an :c:type:`int` type. This might require changes in + your code for properly supporting 64-bit systems. + + +.. c:function:: char* PyString_AsString(PyObject *string) + + Return a NUL-terminated representation of the contents of *string*. The pointer + refers to the internal buffer of *string*, not a copy. The data must not be + modified in any way, unless the string was just created using + ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If + *string* is a Unicode object, this function computes the default encoding of + *string* and operates on that. If *string* is not a string object at all, + :c:func:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`. + + +.. c:function:: char* PyString_AS_STRING(PyObject *string) + + Macro form of :c:func:`PyString_AsString` but without error checking. Only + string objects are supported; no Unicode objects should be passed. + + +.. c:function:: int PyString_AsStringAndSize(PyObject *obj, char **buffer, Py_ssize_t *length) + + Return a NUL-terminated representation of the contents of the object *obj* + through the output variables *buffer* and *length*. + + The function accepts both string and Unicode objects as input. For Unicode + objects it returns the default encoded version of the object. If *length* is + *NULL*, the resulting buffer may not contain NUL characters; if it does, the + function returns ``-1`` and a :exc:`TypeError` is raised. + + The buffer refers to an internal string buffer of *obj*, not a copy. The data + must not be modified in any way, unless the string was just created using + ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If + *string* is a Unicode object, this function computes the default encoding of + *string* and operates on that. If *string* is not a string object at all, + :c:func:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`. + + .. versionchanged:: 2.5 + This function used an :c:type:`int *` type for *length*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. c:function:: void PyString_Concat(PyObject **string, PyObject *newpart) + + Create a new string object in *\*string* containing the contents of *newpart* + appended to *string*; the caller will own the new reference. The reference to + the old value of *string* will be stolen. If the new string cannot be created, + the old reference to *string* will still be discarded and the value of + *\*string* will be set to *NULL*; the appropriate exception will be set. + + +.. c:function:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart) + + Create a new string object in *\*string* containing the contents of *newpart* + appended to *string*. This version decrements the reference count of *newpart*. + + +.. c:function:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize) + + A way to resize a string object even though it is "immutable". Only use this to + build up a brand new string object; don't use this if the string may already be + known in other parts of the code. It is an error to call this function if the + refcount on the input string object is not one. Pass the address of an existing + string object as an lvalue (it may be written into), and the new size desired. + On success, *\*string* holds the resized string object and ``0`` is returned; + the address in *\*string* may differ from its input value. If the reallocation + fails, the original string object at *\*string* is deallocated, *\*string* is + set to *NULL*, a memory exception is set, and ``-1`` is returned. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *newsize*. This might + require changes in your code for properly supporting 64-bit systems. + +.. c:function:: PyObject* PyString_Format(PyObject *format, PyObject *args) + + Return a new string object from *format* and *args*. Analogous to ``format % + args``. The *args* argument must be a tuple. + + +.. c:function:: void PyString_InternInPlace(PyObject **string) + + Intern the argument *\*string* in place. The argument must be the address of a + pointer variable pointing to a Python string object. If there is an existing + interned string that is the same as *\*string*, it sets *\*string* to it + (decrementing the reference count of the old string object and incrementing the + reference count of the interned string object), otherwise it leaves *\*string* + alone and interns it (incrementing its reference count). (Clarification: even + though there is a lot of talk about reference counts, think of this function as + reference-count-neutral; you own the object after the call if and only if you + owned it before the call.) + + .. note:: + + This function is not available in 3.x and does not have a PyBytes alias. + + +.. c:function:: PyObject* PyString_InternFromString(const char *v) + + A combination of :c:func:`PyString_FromString` and + :c:func:`PyString_InternInPlace`, returning either a new string object that has + been interned, or a new ("owned") reference to an earlier interned string object + with the same value. + + .. note:: + + This function is not available in 3.x and does not have a PyBytes alias. + + +.. c:function:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) + + Create an object by decoding *size* bytes of the encoded buffer *s* using the + codec registered for *encoding*. *encoding* and *errors* have the same meaning + as the parameters of the same name in the :func:`unicode` built-in function. + The codec to be used is looked up using the Python codec registry. Return + *NULL* if an exception was raised by the codec. + + .. note:: + + This function is not available in 3.x and does not have a PyBytes alias. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors) + + Decode a string object by passing it to the codec registered for *encoding* and + return the result as Python object. *encoding* and *errors* have the same + meaning as the parameters of the same name in the string :meth:`encode` method. + The codec to be used is looked up using the Python codec registry. Return *NULL* + if an exception was raised by the codec. + + .. note:: + + This function is not available in 3.x and does not have a PyBytes alias. + + +.. c:function:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) + + Encode the :c:type:`char` buffer of the given size by passing it to the codec + registered for *encoding* and return a Python object. *encoding* and *errors* + have the same meaning as the parameters of the same name in the string + :meth:`encode` method. The codec to be used is looked up using the Python codec + registry. Return *NULL* if an exception was raised by the codec. + + .. note:: + + This function is not available in 3.x and does not have a PyBytes alias. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors) + + Encode a string object using the codec registered for *encoding* and return the + result as Python object. *encoding* and *errors* have the same meaning as the + parameters of the same name in the string :meth:`encode` method. The codec to be + used is looked up using the Python codec registry. Return *NULL* if an exception + was raised by the codec. + + .. note:: + + This function is not available in 3.x and does not have a PyBytes alias.
diff --git a/Python-2.7.5/Doc/c-api/structures.rst b/Python-2.7.5/Doc/c-api/structures.rst new file mode 100644 index 0000000..f5007ac --- /dev/null +++ b/Python-2.7.5/Doc/c-api/structures.rst
@@ -0,0 +1,298 @@ +.. 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. It + corresponds to the fields defined by the expansion of the ``PyObject_HEAD`` + macro. + + +.. 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. It corresponds to the + fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro. + +These macros are used in the definition of :c:type:`PyObject` and +:c:type:`PyVarObject`: + + +.. c:macro:: PyObject_HEAD + + This is a macro which expands to the declarations of the fields of the + :c:type:`PyObject` type; it is used when declaring new types which represent + objects without a varying length. The specific fields it expands to depend + on the definition of :c:macro:`Py_TRACE_REFS`. By default, that macro is + not defined, and :c:macro:`PyObject_HEAD` expands to:: + + Py_ssize_t ob_refcnt; + PyTypeObject *ob_type; + + When :c:macro:`Py_TRACE_REFS` is defined, it expands to:: + + PyObject *_ob_next, *_ob_prev; + Py_ssize_t ob_refcnt; + PyTypeObject *ob_type; + + +.. c:macro:: PyObject_VAR_HEAD + + This is a macro which expands to the declarations of the fields of the + :c:type:`PyVarObject` type; it is used when declaring new types which + represent objects with a length that varies from instance to instance. + This macro always expands to:: + + PyObject_HEAD + Py_ssize_t ob_size; + + Note that :c:macro:`PyObject_HEAD` is part of the expansion, and that its own + expansion varies depending on the definition of :c:macro:`Py_TRACE_REFS`. + + +.. 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:: 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 a 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 (but note that :const:`METH_KEYWORDS` +alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). 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 is typically 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. + + +.. data:: METH_OLDARGS + + This calling convention is deprecated. The method must be of type + :c:type:`PyCFunction`. The second argument is *NULL* if no arguments are + given, a single object if exactly one argument is given, and a tuple of + objects if more than one argument is given. There is no way for a function + using this convention to distinguish between a call with multiple arguments + and a call with a tuple as the only 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. + + .. versionadded:: 2.3 + + +.. 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. + + .. versionadded:: 2.3 + +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. + + .. versionadded:: 2.4 + + +.. 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`. Only :c:macro:`T_OBJECT` and :c:macro:`T_OBJECT_EX` + members can be deleted. (They are set to *NULL*). + + +.. c:function:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name) + + Return a bound method object for an extension type implemented in C. This + can be useful in the implementation of a :attr:`tp_getattro` or + :attr:`tp_getattr` handler that does not use the + :c:func:`PyObject_GenericGetAttr` function.
diff --git a/Python-2.7.5/Doc/c-api/sys.rst b/Python-2.7.5/Doc/c-api/sys.rst new file mode 100644 index 0000000..d354e9f --- /dev/null +++ b/Python-2.7.5/Doc/c-api/sys.rst
@@ -0,0 +1,151 @@ +.. highlightlang:: c + +.. _os: + +Operating System Utilities +========================== + + +.. 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)`. + +.. _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(char *name) + + Return the object *name* from the :mod:`sys` module or *NULL* if it does + not exist, without setting an exception. + +.. c:function:: FILE *PySys_GetFile(char *name, FILE *def) + + Return the :c:type:`FILE*` associated with the object *name* in the + :mod:`sys` module, or *def* if *name* is not in the module or is not associated + with a :c:type:`FILE*`. + +.. c:function:: int PySys_SetObject(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(char *s) + + Append *s* to :data:`sys.warnoptions`. + +.. c:function:: void PySys_SetPath(char *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 above, but write to :data:`sys.stderr` or *stderr* instead. + + +.. _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_Finalize() + single: exit() + + Exit the current process. This calls :c:func:`Py_Finalize` and then calls the + standard C library function ``exit(status)``. + + +.. c:function:: int Py_AtExit(void (*func) ()) + + .. index:: + single: Py_Finalize() + single: cleanup functions + + Register a cleanup function to be called by :c:func:`Py_Finalize`. 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*.
diff --git a/Python-2.7.5/Doc/c-api/tuple.rst b/Python-2.7.5/Doc/c-api/tuple.rst new file mode 100644 index 0000000..16de45f --- /dev/null +++ b/Python-2.7.5/Doc/c-api/tuple.rst
@@ -0,0 +1,164 @@ +.. 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 + + .. index:: single: TupleType (in module types) + + This instance of :c:type:`PyTypeObject` represents the Python tuple type; it is + the same object as ``tuple`` and ``types.TupleType`` 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. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. 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. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyTuple_New(Py_ssize_t len) + + Return a new tuple object of size *len*, or *NULL* on failure. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *len*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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)``. + + .. versionadded:: 2.4 + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *n*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: Py_ssize_t PyTuple_Size(PyObject *p) + + Take a pointer to a tuple object, and return the size of that tuple. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *pos*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos) + + Like :c:func:`PyTuple_GetItem`, but does no checking of its arguments. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *pos*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *low* and *high*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. 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*. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *pos*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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*. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *pos*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. 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`. + + .. versionchanged:: 2.2 + Removed unused third parameter, *last_is_sticky*. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *newsize*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. c:function:: int PyTuple_ClearFreeList() + + Clear the free list. Return the total number of freed items. + + .. versionadded:: 2.6
diff --git a/Python-2.7.5/Doc/c-api/type.rst b/Python-2.7.5/Doc/c-api/type.rst new file mode 100644 index 0000000..22f7dd0 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/type.rst
@@ -0,0 +1,96 @@ +.. 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 + + .. index:: single: TypeType (in module types) + + This is the type object for type objects; it is the same object as ``type`` and + ``types.TypeType`` 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. + + .. versionadded:: 2.2 + + +.. c:function:: unsigned int PyType_ClearCache() + + Clear the internal lookup cache. Return the current version tag. + + .. versionadded:: 2.6 + + +.. 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. + + .. versionadded:: 2.6 + + +.. c:function:: int PyType_HasFeature(PyObject *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(PyObject *o) + + Return true if the type object includes support for the cycle detector; this + tests the type flag :const:`Py_TPFLAGS_HAVE_GC`. + + .. versionadded:: 2.0 + + +.. c:function:: int PyType_IsSubtype(PyTypeObject *a, PyTypeObject *b) + + Return true if *a* is a subtype of *b*. + + .. versionadded:: 2.2 + + +.. c:function:: PyObject* PyType_GenericAlloc(PyTypeObject *type, Py_ssize_t nitems) + + .. versionadded:: 2.2 + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *nitems*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds) + + .. versionadded:: 2.2 + + +.. 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. + + .. versionadded:: 2.2
diff --git a/Python-2.7.5/Doc/c-api/typeobj.rst b/Python-2.7.5/Doc/c-api/typeobj.rst new file mode 100644 index 0000000..7c37786 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/typeobj.rst
@@ -0,0 +1,1448 @@ +.. highlightlang:: c + +.. _type-structs: + +Type Objects +============ + +Perhaps one of the most important structures of the Python object system is the +structure that defines a new type: the :c:type:`PyTypeObject` structure. Type +objects can be handled using any of the :c:func:`PyObject_\*` or +:c:func:`PyType_\*` functions, but do not offer much that's interesting to most +Python applications. These objects are fundamental to how objects behave, so +they are very important to the interpreter itself and to any extension module +that implements new types. + +Type objects are fairly large compared to most of the standard types. The reason +for the size is that each type object stores a large number of values, mostly C +function pointers, each of which implements a small part of the type's +functionality. The fields of the type object are examined in detail in this +section. The fields will be described in the order in which they occur in the +structure. + +Typedefs: unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc, +intintargfunc, intobjargproc, intintobjargproc, objobjargproc, destructor, +freefunc, printfunc, getattrfunc, getattrofunc, setattrfunc, setattrofunc, +cmpfunc, reprfunc, hashfunc + +The structure definition for :c:type:`PyTypeObject` can be found in +:file:`Include/object.h`. For convenience of reference, this repeats the +definition found there: + +.. literalinclude:: ../includes/typestruct.h + + +The type object structure extends the :c:type:`PyVarObject` structure. The +:attr:`ob_size` field is used for dynamic types (created by :func:`type_new`, +usually called from a class statement). Note that :c:data:`PyType_Type` (the +metatype) initializes :attr:`tp_itemsize`, which means that its instances (i.e. +type objects) *must* have the :attr:`ob_size` field. + + +.. c:member:: PyObject* PyObject._ob_next + PyObject* PyObject._ob_prev + + These fields are only present when the macro ``Py_TRACE_REFS`` is defined. + Their initialization to *NULL* is taken care of by the ``PyObject_HEAD_INIT`` + macro. For statically allocated objects, these fields always remain *NULL*. + For dynamically allocated objects, these two fields are used to link the object + into a doubly-linked list of *all* live objects on the heap. This could be used + for various debugging purposes; currently the only use is to print the objects + that are still alive at the end of a run when the environment variable + :envvar:`PYTHONDUMPREFS` is set. + + These fields are not inherited by subtypes. + + +.. c:member:: Py_ssize_t PyObject.ob_refcnt + + This is the type object's reference count, initialized to ``1`` by the + ``PyObject_HEAD_INIT`` macro. Note that for statically allocated type objects, + the type's instances (objects whose :attr:`ob_type` points back to the type) do + *not* count as references. But for dynamically allocated type objects, the + instances *do* count as references. + + This field is not inherited by subtypes. + + .. versionchanged:: 2.5 + This field used to be an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. c:member:: PyTypeObject* PyObject.ob_type + + This is the type's type, in other words its metatype. It is initialized by the + argument to the ``PyObject_HEAD_INIT`` macro, and its value should normally be + ``&PyType_Type``. However, for dynamically loadable extension modules that must + be usable on Windows (at least), the compiler complains that this is not a valid + initializer. Therefore, the convention is to pass *NULL* to the + ``PyObject_HEAD_INIT`` macro and to initialize this field explicitly at the + start of the module's initialization function, before doing anything else. This + is typically done like this:: + + Foo_Type.ob_type = &PyType_Type; + + This should be done before any instances of the type are created. + :c:func:`PyType_Ready` checks if :attr:`ob_type` is *NULL*, and if so, + initializes it: in Python 2.2, it is set to ``&PyType_Type``; in Python 2.2.1 + and later it is initialized to the :attr:`ob_type` field of the base class. + :c:func:`PyType_Ready` will not change this field if it is non-zero. + + In Python 2.2, this field is not inherited by subtypes. In 2.2.1, and in 2.3 + and beyond, it is inherited by subtypes. + + +.. c:member:: Py_ssize_t PyVarObject.ob_size + + For statically allocated type objects, this should be initialized to zero. For + dynamically allocated type objects, this field has a special internal meaning. + + This field is not inherited by subtypes. + + +.. c:member:: char* PyTypeObject.tp_name + + Pointer to a NUL-terminated string containing the name of the type. For types + that are accessible as module globals, the string should be the full module + name, followed by a dot, followed by the type name; for built-in types, it + should be just the type name. If the module is a submodule of a package, the + full package name is part of the full module name. For example, a type named + :class:`T` defined in module :mod:`M` in subpackage :mod:`Q` in package :mod:`P` + should have the :attr:`tp_name` initializer ``"P.Q.M.T"``. + + For dynamically allocated type objects, this should just be the type name, and + the module name explicitly stored in the type dict as the value for key + ``'__module__'``. + + For statically allocated type objects, the tp_name field should contain a dot. + Everything before the last dot is made accessible as the :attr:`__module__` + attribute, and everything after the last dot is made accessible as the + :attr:`__name__` attribute. + + If no dot is present, the entire :attr:`tp_name` field is made accessible as the + :attr:`__name__` attribute, and the :attr:`__module__` attribute is undefined + (unless explicitly set in the dictionary, as explained above). This means your + type will be impossible to pickle. + + This field is not inherited by subtypes. + + +.. c:member:: Py_ssize_t PyTypeObject.tp_basicsize + Py_ssize_t PyTypeObject.tp_itemsize + + These fields allow calculating the size in bytes of instances of the type. + + There are two kinds of types: types with fixed-length instances have a zero + :attr:`tp_itemsize` field, types with variable-length instances have a non-zero + :attr:`tp_itemsize` field. For a type with fixed-length instances, all + instances have the same size, given in :attr:`tp_basicsize`. + + For a type with variable-length instances, the instances must have an + :attr:`ob_size` field, and the instance size is :attr:`tp_basicsize` plus N + times :attr:`tp_itemsize`, where N is the "length" of the object. The value of + N is typically stored in the instance's :attr:`ob_size` field. There are + exceptions: for example, long ints use a negative :attr:`ob_size` to indicate a + negative number, and N is ``abs(ob_size)`` there. Also, the presence of an + :attr:`ob_size` field in the instance layout doesn't mean that the instance + structure is variable-length (for example, the structure for the list type has + fixed-length instances, yet those instances have a meaningful :attr:`ob_size` + field). + + The basic size includes the fields in the instance declared by the macro + :c:macro:`PyObject_HEAD` or :c:macro:`PyObject_VAR_HEAD` (whichever is used to + declare the instance struct) and this in turn includes the :attr:`_ob_prev` and + :attr:`_ob_next` fields if they are present. This means that the only correct + way to get an initializer for the :attr:`tp_basicsize` is to use the + ``sizeof`` operator on the struct used to declare the instance layout. + The basic size does not include the GC header size (this is new in Python 2.2; + in 2.1 and 2.0, the GC header size was included in :attr:`tp_basicsize`). + + These fields are inherited separately by subtypes. If the base type has a + non-zero :attr:`tp_itemsize`, it is generally not safe to set + :attr:`tp_itemsize` to a different non-zero value in a subtype (though this + depends on the implementation of the base type). + + A note about alignment: if the variable items require a particular alignment, + this should be taken care of by the value of :attr:`tp_basicsize`. Example: + suppose a type implements an array of ``double``. :attr:`tp_itemsize` is + ``sizeof(double)``. It is the programmer's responsibility that + :attr:`tp_basicsize` is a multiple of ``sizeof(double)`` (assuming this is the + alignment requirement for ``double``). + + +.. c:member:: destructor PyTypeObject.tp_dealloc + + A pointer to the instance destructor function. This function must be defined + unless the type guarantees that its instances will never be deallocated (as is + the case for the singletons ``None`` and ``Ellipsis``). + + The destructor function is called by the :c:func:`Py_DECREF` and + :c:func:`Py_XDECREF` macros when the new reference count is zero. At this point, + the instance is still in existence, but there are no references to it. The + destructor function should free all references which the instance owns, free all + memory buffers owned by the instance (using the freeing function corresponding + to the allocation function used to allocate the buffer), and finally (as its + last action) call the type's :attr:`tp_free` function. If the type is not + subtypable (doesn't have the :const:`Py_TPFLAGS_BASETYPE` flag bit set), it is + permissible to call the object deallocator directly instead of via + :attr:`tp_free`. The object deallocator should be the one used to allocate the + instance; this is normally :c:func:`PyObject_Del` if the instance was allocated + using :c:func:`PyObject_New` or :c:func:`PyObject_VarNew`, or + :c:func:`PyObject_GC_Del` if the instance was allocated using + :c:func:`PyObject_GC_New` or :c:func:`PyObject_GC_NewVar`. + + This field is inherited by subtypes. + + +.. c:member:: printfunc PyTypeObject.tp_print + + An optional pointer to the instance print function. + + The print function is only called when the instance is printed to a *real* file; + when it is printed to a pseudo-file (like a :class:`StringIO` instance), the + instance's :attr:`tp_repr` or :attr:`tp_str` function is called to convert it to + a string. These are also called when the type's :attr:`tp_print` field is + *NULL*. A type should never implement :attr:`tp_print` in a way that produces + different output than :attr:`tp_repr` or :attr:`tp_str` would. + + The print function is called with the same signature as :c:func:`PyObject_Print`: + ``int tp_print(PyObject *self, FILE *file, int flags)``. The *self* argument is + the instance to be printed. The *file* argument is the stdio file to which it + is to be printed. The *flags* argument is composed of flag bits. The only flag + bit currently defined is :const:`Py_PRINT_RAW`. When the :const:`Py_PRINT_RAW` + flag bit is set, the instance should be printed the same way as :attr:`tp_str` + would format it; when the :const:`Py_PRINT_RAW` flag bit is clear, the instance + should be printed the same was as :attr:`tp_repr` would format it. It should + return ``-1`` and set an exception condition when an error occurred during the + comparison. + + It is possible that the :attr:`tp_print` field will be deprecated. In any case, + it is recommended not to define :attr:`tp_print`, but instead to rely on + :attr:`tp_repr` and :attr:`tp_str` for printing. + + This field is inherited by subtypes. + + +.. c:member:: getattrfunc PyTypeObject.tp_getattr + + An optional pointer to the get-attribute-string function. + + This field is deprecated. When it is defined, it should point to a function + that acts the same as the :attr:`tp_getattro` function, but taking a C string + instead of a Python string object to give the attribute name. The signature is + the same as for :c:func:`PyObject_GetAttrString`. + + This field is inherited by subtypes together with :attr:`tp_getattro`: a subtype + inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when + the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*. + + +.. c:member:: setattrfunc PyTypeObject.tp_setattr + + An optional pointer to the set-attribute-string function. + + This field is deprecated. When it is defined, it should point to a function + that acts the same as the :attr:`tp_setattro` function, but taking a C string + instead of a Python string object to give the attribute name. The signature is + the same as for :c:func:`PyObject_SetAttrString`. + + This field is inherited by subtypes together with :attr:`tp_setattro`: a subtype + inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when + the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*. + + +.. c:member:: cmpfunc PyTypeObject.tp_compare + + An optional pointer to the three-way comparison function. + + The signature is the same as for :c:func:`PyObject_Compare`. The function should + return ``1`` if *self* greater than *other*, ``0`` if *self* is equal to + *other*, and ``-1`` if *self* less than *other*. It should return ``-1`` and + set an exception condition when an error occurred during the comparison. + + This field is inherited by subtypes together with :attr:`tp_richcompare` and + :attr:`tp_hash`: a subtypes inherits all three of :attr:`tp_compare`, + :attr:`tp_richcompare`, and :attr:`tp_hash` when the subtype's + :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*. + + +.. c:member:: reprfunc PyTypeObject.tp_repr + + .. index:: builtin: repr + + An optional pointer to a function that implements the built-in function + :func:`repr`. + + The signature is the same as for :c:func:`PyObject_Repr`; it must return a string + or a Unicode object. Ideally, this function should return a string that, when + passed to :func:`eval`, given a suitable environment, returns an object with the + same value. If this is not feasible, it should return a string starting with + ``'<'`` and ending with ``'>'`` from which both the type and the value of the + object can be deduced. + + When this field is not set, a string of the form ``<%s object at %p>`` is + returned, where ``%s`` is replaced by the type name, and ``%p`` by the object's + memory address. + + This field is inherited by subtypes. + +.. c:member:: PyNumberMethods* tp_as_number + + Pointer to an additional structure that contains fields relevant only to + objects which implement the number protocol. These fields are documented in + :ref:`number-structs`. + + The :attr:`tp_as_number` field is not inherited, but the contained fields are + inherited individually. + + +.. c:member:: PySequenceMethods* tp_as_sequence + + Pointer to an additional structure that contains fields relevant only to + objects which implement the sequence protocol. These fields are documented + in :ref:`sequence-structs`. + + The :attr:`tp_as_sequence` field is not inherited, but the contained fields + are inherited individually. + + +.. c:member:: PyMappingMethods* tp_as_mapping + + Pointer to an additional structure that contains fields relevant only to + objects which implement the mapping protocol. These fields are documented in + :ref:`mapping-structs`. + + The :attr:`tp_as_mapping` field is not inherited, but the contained fields + are inherited individually. + + +.. c:member:: hashfunc PyTypeObject.tp_hash + + .. index:: builtin: hash + + An optional pointer to a function that implements the built-in function + :func:`hash`. + + The signature is the same as for :c:func:`PyObject_Hash`; it must return a C + long. The value ``-1`` should not be returned as a normal return value; when an + error occurs during the computation of the hash value, the function should set + an exception and return ``-1``. + + This field can be set explicitly to :c:func:`PyObject_HashNotImplemented` to + block inheritance of the hash method from a parent type. This is interpreted + as the equivalent of ``__hash__ = None`` at the Python level, causing + ``isinstance(o, collections.Hashable)`` to correctly return ``False``. Note + that the converse is also true - setting ``__hash__ = None`` on a class at + the Python level will result in the ``tp_hash`` slot being set to + :c:func:`PyObject_HashNotImplemented`. + + When this field is not set, two possibilities exist: if the :attr:`tp_compare` + and :attr:`tp_richcompare` fields are both *NULL*, a default hash value based on + the object's address is returned; otherwise, a :exc:`TypeError` is raised. + + This field is inherited by subtypes together with :attr:`tp_richcompare` and + :attr:`tp_compare`: a subtypes inherits all three of :attr:`tp_compare`, + :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's + :attr:`tp_compare`, :attr:`tp_richcompare` and :attr:`tp_hash` are all *NULL*. + + +.. c:member:: ternaryfunc PyTypeObject.tp_call + + An optional pointer to a function that implements calling the object. This + should be *NULL* if the object is not callable. The signature is the same as + for :c:func:`PyObject_Call`. + + This field is inherited by subtypes. + + +.. c:member:: reprfunc PyTypeObject.tp_str + + An optional pointer to a function that implements the built-in operation + :func:`str`. (Note that :class:`str` is a type now, and :func:`str` calls the + constructor for that type. This constructor calls :c:func:`PyObject_Str` to do + the actual work, and :c:func:`PyObject_Str` will call this handler.) + + The signature is the same as for :c:func:`PyObject_Str`; it must return a string + or a Unicode object. This function should return a "friendly" string + representation of the object, as this is the representation that will be used by + the print statement. + + When this field is not set, :c:func:`PyObject_Repr` is called to return a string + representation. + + This field is inherited by subtypes. + + +.. c:member:: getattrofunc PyTypeObject.tp_getattro + + An optional pointer to the get-attribute function. + + The signature is the same as for :c:func:`PyObject_GetAttr`. It is usually + convenient to set this field to :c:func:`PyObject_GenericGetAttr`, which + implements the normal way of looking for object attributes. + + This field is inherited by subtypes together with :attr:`tp_getattr`: a subtype + inherits both :attr:`tp_getattr` and :attr:`tp_getattro` from its base type when + the subtype's :attr:`tp_getattr` and :attr:`tp_getattro` are both *NULL*. + + +.. c:member:: setattrofunc PyTypeObject.tp_setattro + + An optional pointer to the set-attribute function. + + The signature is the same as for :c:func:`PyObject_SetAttr`. It is usually + convenient to set this field to :c:func:`PyObject_GenericSetAttr`, which + implements the normal way of setting object attributes. + + This field is inherited by subtypes together with :attr:`tp_setattr`: a subtype + inherits both :attr:`tp_setattr` and :attr:`tp_setattro` from its base type when + the subtype's :attr:`tp_setattr` and :attr:`tp_setattro` are both *NULL*. + + +.. c:member:: PyBufferProcs* PyTypeObject.tp_as_buffer + + Pointer to an additional structure that contains fields relevant only to objects + which implement the buffer interface. These fields are documented in + :ref:`buffer-structs`. + + The :attr:`tp_as_buffer` field is not inherited, but the contained fields are + inherited individually. + + +.. c:member:: long PyTypeObject.tp_flags + + This field is a bit mask of various flags. Some flags indicate variant + semantics for certain situations; others are used to indicate that certain + fields in the type object (or in the extension structures referenced via + :attr:`tp_as_number`, :attr:`tp_as_sequence`, :attr:`tp_as_mapping`, and + :attr:`tp_as_buffer`) that were historically not always present are valid; if + such a flag bit is clear, the type fields it guards must not be accessed and + must be considered to have a zero or *NULL* value instead. + + Inheritance of this field is complicated. Most flag bits are inherited + individually, i.e. if the base type has a flag bit set, the subtype inherits + this flag bit. The flag bits that pertain to extension structures are strictly + inherited if the extension structure is inherited, i.e. the base type's value of + the flag bit is copied into the subtype together with a pointer to the extension + structure. The :const:`Py_TPFLAGS_HAVE_GC` flag bit is inherited together with + the :attr:`tp_traverse` and :attr:`tp_clear` fields, i.e. if the + :const:`Py_TPFLAGS_HAVE_GC` flag bit is clear in the subtype and the + :attr:`tp_traverse` and :attr:`tp_clear` fields in the subtype exist (as + indicated by the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit) and have *NULL* + values. + + The following bit masks are currently defined; these can be ORed together using + the ``|`` operator to form the value of the :attr:`tp_flags` field. The macro + :c:func:`PyType_HasFeature` takes a type and a flags value, *tp* and *f*, and + checks whether ``tp->tp_flags & f`` is non-zero. + + + .. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER + + If this bit is set, the :c:type:`PyBufferProcs` struct referenced by + :attr:`tp_as_buffer` has the :attr:`bf_getcharbuffer` field. + + + .. data:: Py_TPFLAGS_HAVE_SEQUENCE_IN + + If this bit is set, the :c:type:`PySequenceMethods` struct referenced by + :attr:`tp_as_sequence` has the :attr:`sq_contains` field. + + + .. data:: Py_TPFLAGS_GC + + This bit is obsolete. The bit it used to name is no longer in use. The symbol + is now defined as zero. + + + .. data:: Py_TPFLAGS_HAVE_INPLACEOPS + + If this bit is set, the :c:type:`PySequenceMethods` struct referenced by + :attr:`tp_as_sequence` and the :c:type:`PyNumberMethods` structure referenced by + :attr:`tp_as_number` contain the fields for in-place operators. In particular, + this means that the :c:type:`PyNumberMethods` structure has the fields + :attr:`nb_inplace_add`, :attr:`nb_inplace_subtract`, + :attr:`nb_inplace_multiply`, :attr:`nb_inplace_divide`, + :attr:`nb_inplace_remainder`, :attr:`nb_inplace_power`, + :attr:`nb_inplace_lshift`, :attr:`nb_inplace_rshift`, :attr:`nb_inplace_and`, + :attr:`nb_inplace_xor`, and :attr:`nb_inplace_or`; and the + :c:type:`PySequenceMethods` struct has the fields :attr:`sq_inplace_concat` and + :attr:`sq_inplace_repeat`. + + + .. data:: Py_TPFLAGS_CHECKTYPES + + If this bit is set, the binary and ternary operations in the + :c:type:`PyNumberMethods` structure referenced by :attr:`tp_as_number` accept + arguments of arbitrary object types, and do their own type conversions if + needed. If this bit is clear, those operations require that all arguments have + the current type as their type, and the caller is supposed to perform a coercion + operation first. This applies to :attr:`nb_add`, :attr:`nb_subtract`, + :attr:`nb_multiply`, :attr:`nb_divide`, :attr:`nb_remainder`, :attr:`nb_divmod`, + :attr:`nb_power`, :attr:`nb_lshift`, :attr:`nb_rshift`, :attr:`nb_and`, + :attr:`nb_xor`, and :attr:`nb_or`. + + + .. data:: Py_TPFLAGS_HAVE_RICHCOMPARE + + If this bit is set, the type object has the :attr:`tp_richcompare` field, as + well as the :attr:`tp_traverse` and the :attr:`tp_clear` fields. + + + .. data:: Py_TPFLAGS_HAVE_WEAKREFS + + If this bit is set, the :attr:`tp_weaklistoffset` field is defined. Instances + of a type are weakly referenceable if the type's :attr:`tp_weaklistoffset` field + has a value greater than zero. + + + .. data:: Py_TPFLAGS_HAVE_ITER + + If this bit is set, the type object has the :attr:`tp_iter` and + :attr:`tp_iternext` fields. + + + .. data:: Py_TPFLAGS_HAVE_CLASS + + If this bit is set, the type object has several new fields defined starting in + Python 2.2: :attr:`tp_methods`, :attr:`tp_members`, :attr:`tp_getset`, + :attr:`tp_base`, :attr:`tp_dict`, :attr:`tp_descr_get`, :attr:`tp_descr_set`, + :attr:`tp_dictoffset`, :attr:`tp_init`, :attr:`tp_alloc`, :attr:`tp_new`, + :attr:`tp_free`, :attr:`tp_is_gc`, :attr:`tp_bases`, :attr:`tp_mro`, + :attr:`tp_cache`, :attr:`tp_subclasses`, and :attr:`tp_weaklist`. + + + .. data:: Py_TPFLAGS_HEAPTYPE + + This bit is set when the type object itself is allocated on the heap. In this + case, the :attr:`ob_type` field of its instances is considered a reference to + the type, and the type object is INCREF'ed when a new instance is created, and + DECREF'ed when an instance is destroyed (this does not apply to instances of + subtypes; only the type referenced by the instance's ob_type gets INCREF'ed or + DECREF'ed). + + + .. data:: Py_TPFLAGS_BASETYPE + + This bit is set when the type can be used as the base type of another type. If + this bit is clear, the type cannot be subtyped (similar to a "final" class in + Java). + + + .. data:: Py_TPFLAGS_READY + + This bit is set when the type object has been fully initialized by + :c:func:`PyType_Ready`. + + + .. data:: Py_TPFLAGS_READYING + + This bit is set while :c:func:`PyType_Ready` is in the process of initializing + the type object. + + + .. data:: Py_TPFLAGS_HAVE_GC + + This bit is set when the object supports garbage collection. If this bit + is set, instances must be created using :c:func:`PyObject_GC_New` and + destroyed using :c:func:`PyObject_GC_Del`. More information in section + :ref:`supporting-cycle-detection`. This bit also implies that the + GC-related fields :attr:`tp_traverse` and :attr:`tp_clear` are present in + the type object; but those fields also exist when + :const:`Py_TPFLAGS_HAVE_GC` is clear but + :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` is set. + + + .. data:: Py_TPFLAGS_DEFAULT + + This is a bitmask of all the bits that pertain to the existence of certain + fields in the type object and its extension structures. Currently, it includes + the following bits: :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER`, + :const:`Py_TPFLAGS_HAVE_SEQUENCE_IN`, :const:`Py_TPFLAGS_HAVE_INPLACEOPS`, + :const:`Py_TPFLAGS_HAVE_RICHCOMPARE`, :const:`Py_TPFLAGS_HAVE_WEAKREFS`, + :const:`Py_TPFLAGS_HAVE_ITER`, and :const:`Py_TPFLAGS_HAVE_CLASS`. + + +.. c:member:: char* PyTypeObject.tp_doc + + An optional pointer to a NUL-terminated C string giving the docstring for this + type object. This is exposed as the :attr:`__doc__` attribute on the type and + instances of the type. + + This field is *not* inherited by subtypes. + +The following three fields only exist if the +:const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag bit is set. + + +.. c:member:: traverseproc PyTypeObject.tp_traverse + + An optional pointer to a traversal function for the garbage collector. This is + only used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. More information + about Python's garbage collection scheme can be found in section + :ref:`supporting-cycle-detection`. + + The :attr:`tp_traverse` pointer is used by the garbage collector to detect + reference cycles. A typical implementation of a :attr:`tp_traverse` function + simply calls :c:func:`Py_VISIT` on each of the instance's members that are Python + objects. For example, this is function :c:func:`local_traverse` from the + :mod:`thread` extension module:: + + static int + local_traverse(localobject *self, visitproc visit, void *arg) + { + Py_VISIT(self->args); + Py_VISIT(self->kw); + Py_VISIT(self->dict); + return 0; + } + + Note that :c:func:`Py_VISIT` is called only on those members that can participate + in reference cycles. Although there is also a ``self->key`` member, it can only + be *NULL* or a Python string and therefore cannot be part of a reference cycle. + + On the other hand, even if you know a member can never be part of a cycle, as a + debugging aid you may want to visit it anyway just so the :mod:`gc` module's + :func:`get_referents` function will include it. + + Note that :c:func:`Py_VISIT` requires the *visit* and *arg* parameters to + :c:func:`local_traverse` to have these specific names; don't name them just + anything. + + This field is inherited by subtypes together with :attr:`tp_clear` and the + :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and + :attr:`tp_clear` are all inherited from the base type if they are all zero in + the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag + bit set. + + +.. c:member:: inquiry PyTypeObject.tp_clear + + An optional pointer to a clear function for the garbage collector. This is only + used if the :const:`Py_TPFLAGS_HAVE_GC` flag bit is set. + + The :attr:`tp_clear` member function is used to break reference cycles in cyclic + garbage detected by the garbage collector. Taken together, all :attr:`tp_clear` + functions in the system must combine to break all reference cycles. This is + subtle, and if in any doubt supply a :attr:`tp_clear` function. For example, + the tuple type does not implement a :attr:`tp_clear` function, because it's + possible to prove that no reference cycle can be composed entirely of tuples. + Therefore the :attr:`tp_clear` functions of other types must be sufficient to + break any cycle containing a tuple. This isn't immediately obvious, and there's + rarely a good reason to avoid implementing :attr:`tp_clear`. + + Implementations of :attr:`tp_clear` should drop the instance's references to + those of its members that may be Python objects, and set its pointers to those + members to *NULL*, as in the following example:: + + static int + local_clear(localobject *self) + { + Py_CLEAR(self->key); + Py_CLEAR(self->args); + Py_CLEAR(self->kw); + Py_CLEAR(self->dict); + return 0; + } + + The :c:func:`Py_CLEAR` macro should be used, because clearing references is + delicate: the reference to the contained object must not be decremented until + after the pointer to the contained object is set to *NULL*. This is because + decrementing the reference count may cause the contained object to become trash, + triggering a chain of reclamation activity that may include invoking arbitrary + Python code (due to finalizers, or weakref callbacks, associated with the + contained object). If it's possible for such code to reference *self* again, + it's important that the pointer to the contained object be *NULL* at that time, + so that *self* knows the contained object can no longer be used. The + :c:func:`Py_CLEAR` macro performs the operations in a safe order. + + Because the goal of :attr:`tp_clear` functions is to break reference cycles, + it's not necessary to clear contained objects like Python strings or Python + integers, which can't participate in reference cycles. On the other hand, it may + be convenient to clear all contained Python objects, and write the type's + :attr:`tp_dealloc` function to invoke :attr:`tp_clear`. + + More information about Python's garbage collection scheme can be found in + section :ref:`supporting-cycle-detection`. + + This field is inherited by subtypes together with :attr:`tp_traverse` and the + :const:`Py_TPFLAGS_HAVE_GC` flag bit: the flag bit, :attr:`tp_traverse`, and + :attr:`tp_clear` are all inherited from the base type if they are all zero in + the subtype *and* the subtype has the :const:`Py_TPFLAGS_HAVE_RICHCOMPARE` flag + bit set. + + +.. c:member:: richcmpfunc PyTypeObject.tp_richcompare + + An optional pointer to the rich comparison function, whose signature is + ``PyObject *tp_richcompare(PyObject *a, PyObject *b, int op)``. + + The function should return the result of the comparison (usually ``Py_True`` + or ``Py_False``). If the comparison is undefined, it must return + ``Py_NotImplemented``, if another error occurred it must return ``NULL`` and + set an exception condition. + + .. note:: + + If you want to implement a type for which only a limited set of + comparisons makes sense (e.g. ``==`` and ``!=``, but not ``<`` and + friends), directly raise :exc:`TypeError` in the rich comparison function. + + This field is inherited by subtypes together with :attr:`tp_compare` and + :attr:`tp_hash`: a subtype inherits all three of :attr:`tp_compare`, + :attr:`tp_richcompare`, and :attr:`tp_hash`, when the subtype's + :attr:`tp_compare`, :attr:`tp_richcompare`, and :attr:`tp_hash` are all *NULL*. + + The following constants are defined to be used as the third argument for + :attr:`tp_richcompare` and for :c:func:`PyObject_RichCompare`: + + +----------------+------------+ + | Constant | Comparison | + +================+============+ + | :const:`Py_LT` | ``<`` | + +----------------+------------+ + | :const:`Py_LE` | ``<=`` | + +----------------+------------+ + | :const:`Py_EQ` | ``==`` | + +----------------+------------+ + | :const:`Py_NE` | ``!=`` | + +----------------+------------+ + | :const:`Py_GT` | ``>`` | + +----------------+------------+ + | :const:`Py_GE` | ``>=`` | + +----------------+------------+ + + +The next field only exists if the :const:`Py_TPFLAGS_HAVE_WEAKREFS` flag bit is +set. + +.. c:member:: long PyTypeObject.tp_weaklistoffset + + If the instances of this type are weakly referenceable, this field is greater + than zero and contains the offset in the instance structure of the weak + reference list head (ignoring the GC header, if present); this offset is used by + :c:func:`PyObject_ClearWeakRefs` and the :c:func:`PyWeakref_\*` functions. The + instance structure needs to include a field of type :c:type:`PyObject\*` which is + initialized to *NULL*. + + Do not confuse this field with :attr:`tp_weaklist`; that is the list head for + weak references to the type object itself. + + This field is inherited by subtypes, but see the rules listed below. A subtype + may override this offset; this means that the subtype uses a different weak + reference list head than the base type. Since the list head is always found via + :attr:`tp_weaklistoffset`, this should not be a problem. + + When a type defined by a class statement has no :attr:`__slots__` declaration, + and none of its base types are weakly referenceable, the type is made weakly + referenceable by adding a weak reference list head slot to the instance layout + and setting the :attr:`tp_weaklistoffset` of that slot's offset. + + When a type's :attr:`__slots__` declaration contains a slot named + :attr:`__weakref__`, that slot becomes the weak reference list head for + instances of the type, and the slot's offset is stored in the type's + :attr:`tp_weaklistoffset`. + + When a type's :attr:`__slots__` declaration does not contain a slot named + :attr:`__weakref__`, the type inherits its :attr:`tp_weaklistoffset` from its + base type. + +The next two fields only exist if the :const:`Py_TPFLAGS_HAVE_ITER` flag bit is +set. + + +.. c:member:: getiterfunc PyTypeObject.tp_iter + + An optional pointer to a function that returns an iterator for the object. Its + presence normally signals that the instances of this type are iterable (although + sequences may be iterable without this function, and classic instances always + have this function, even if they don't define an :meth:`__iter__` method). + + This function has the same signature as :c:func:`PyObject_GetIter`. + + This field is inherited by subtypes. + + +.. c:member:: iternextfunc PyTypeObject.tp_iternext + + An optional pointer to a function that returns the next item in an iterator. + When the iterator is exhausted, it must return *NULL*; a :exc:`StopIteration` + exception may or may not be set. When another error occurs, it must return + *NULL* too. Its presence normally signals that the instances of this type + are iterators (although classic instances always have this function, even if + they don't define a :meth:`next` method). + + Iterator types should also define the :attr:`tp_iter` function, and that + function should return the iterator instance itself (not a new iterator + instance). + + This function has the same signature as :c:func:`PyIter_Next`. + + This field is inherited by subtypes. + +The next fields, up to and including :attr:`tp_weaklist`, only exist if the +:const:`Py_TPFLAGS_HAVE_CLASS` flag bit is set. + + +.. c:member:: struct PyMethodDef* PyTypeObject.tp_methods + + An optional pointer to a static *NULL*-terminated array of :c:type:`PyMethodDef` + structures, declaring regular methods of this type. + + For each entry in the array, an entry is added to the type's dictionary (see + :attr:`tp_dict` below) containing a method descriptor. + + This field is not inherited by subtypes (methods are inherited through a + different mechanism). + + +.. c:member:: struct PyMemberDef* PyTypeObject.tp_members + + An optional pointer to a static *NULL*-terminated array of :c:type:`PyMemberDef` + structures, declaring regular data members (fields or slots) of instances of + this type. + + For each entry in the array, an entry is added to the type's dictionary (see + :attr:`tp_dict` below) containing a member descriptor. + + This field is not inherited by subtypes (members are inherited through a + different mechanism). + + +.. c:member:: struct PyGetSetDef* PyTypeObject.tp_getset + + An optional pointer to a static *NULL*-terminated array of :c:type:`PyGetSetDef` + structures, declaring computed attributes of instances of this type. + + For each entry in the array, an entry is added to the type's dictionary (see + :attr:`tp_dict` below) containing a getset descriptor. + + This field is not inherited by subtypes (computed attributes are inherited + through a different mechanism). + + .. XXX belongs elsewhere + + Docs for PyGetSetDef:: + + typedef PyObject *(*getter)(PyObject *, void *); + typedef int (*setter)(PyObject *, PyObject *, void *); + + typedef struct PyGetSetDef { + char *name; /* attribute name */ + getter get; /* C function to get the attribute */ + setter set; /* C function to set the attribute */ + char *doc; /* optional doc string */ + void *closure; /* optional additional data for getter and setter */ + } PyGetSetDef; + + +.. c:member:: PyTypeObject* PyTypeObject.tp_base + + An optional pointer to a base type from which type properties are inherited. At + this level, only single inheritance is supported; multiple inheritance require + dynamically creating a type object by calling the metatype. + + This field is not inherited by subtypes (obviously), but it defaults to + ``&PyBaseObject_Type`` (which to Python programmers is known as the type + :class:`object`). + + +.. c:member:: PyObject* PyTypeObject.tp_dict + + The type's dictionary is stored here by :c:func:`PyType_Ready`. + + This field should normally be initialized to *NULL* before PyType_Ready is + called; it may also be initialized to a dictionary containing initial attributes + for the type. Once :c:func:`PyType_Ready` has initialized the type, extra + attributes for the type may be added to this dictionary only if they don't + correspond to overloaded operations (like :meth:`__add__`). + + This field is not inherited by subtypes (though the attributes defined in here + are inherited through a different mechanism). + + +.. c:member:: descrgetfunc PyTypeObject.tp_descr_get + + An optional pointer to a "descriptor get" function. + + The function signature is :: + + PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type); + + .. XXX explain. + + This field is inherited by subtypes. + + +.. c:member:: descrsetfunc PyTypeObject.tp_descr_set + + An optional pointer to a "descriptor set" function. + + The function signature is :: + + int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value); + + This field is inherited by subtypes. + + .. XXX explain. + + +.. c:member:: long PyTypeObject.tp_dictoffset + + If the instances of this type have a dictionary containing instance variables, + this field is non-zero and contains the offset in the instances of the type of + the instance variable dictionary; this offset is used by + :c:func:`PyObject_GenericGetAttr`. + + Do not confuse this field with :attr:`tp_dict`; that is the dictionary for + attributes of the type object itself. + + If the value of this field is greater than zero, it specifies the offset from + the start of the instance structure. If the value is less than zero, it + specifies the offset from the *end* of the instance structure. A negative + offset is more expensive to use, and should only be used when the instance + structure contains a variable-length part. This is used for example to add an + instance variable dictionary to subtypes of :class:`str` or :class:`tuple`. Note + that the :attr:`tp_basicsize` field should account for the dictionary added to + the end in that case, even though the dictionary is not included in the basic + object layout. On a system with a pointer size of 4 bytes, + :attr:`tp_dictoffset` should be set to ``-4`` to indicate that the dictionary is + at the very end of the structure. + + The real dictionary offset in an instance can be computed from a negative + :attr:`tp_dictoffset` as follows:: + + dictoffset = tp_basicsize + abs(ob_size)*tp_itemsize + tp_dictoffset + if dictoffset is not aligned on sizeof(void*): + round up to sizeof(void*) + + where :attr:`tp_basicsize`, :attr:`tp_itemsize` and :attr:`tp_dictoffset` are + taken from the type object, and :attr:`ob_size` is taken from the instance. The + absolute value is taken because long ints use the sign of :attr:`ob_size` to + store the sign of the number. (There's never a need to do this calculation + yourself; it is done for you by :c:func:`_PyObject_GetDictPtr`.) + + This field is inherited by subtypes, but see the rules listed below. A subtype + may override this offset; this means that the subtype instances store the + dictionary at a difference offset than the base type. Since the dictionary is + always found via :attr:`tp_dictoffset`, this should not be a problem. + + When a type defined by a class statement has no :attr:`__slots__` declaration, + and none of its base types has an instance variable dictionary, a dictionary + slot is added to the instance layout and the :attr:`tp_dictoffset` is set to + that slot's offset. + + When a type defined by a class statement has a :attr:`__slots__` declaration, + the type inherits its :attr:`tp_dictoffset` from its base type. + + (Adding a slot named :attr:`__dict__` to the :attr:`__slots__` declaration does + not have the expected effect, it just causes confusion. Maybe this should be + added as a feature just like :attr:`__weakref__` though.) + + +.. c:member:: initproc PyTypeObject.tp_init + + An optional pointer to an instance initialization function. + + This function corresponds to the :meth:`__init__` method of classes. Like + :meth:`__init__`, it is possible to create an instance without calling + :meth:`__init__`, and it is possible to reinitialize an instance by calling its + :meth:`__init__` method again. + + The function signature is :: + + int tp_init(PyObject *self, PyObject *args, PyObject *kwds) + + The self argument is the instance to be initialized; the *args* and *kwds* + arguments represent positional and keyword arguments of the call to + :meth:`__init__`. + + The :attr:`tp_init` function, if not *NULL*, is called when an instance is + created normally by calling its type, after the type's :attr:`tp_new` function + has returned an instance of the type. If the :attr:`tp_new` function returns an + instance of some other type that is not a subtype of the original type, no + :attr:`tp_init` function is called; if :attr:`tp_new` returns an instance of a + subtype of the original type, the subtype's :attr:`tp_init` is called. (VERSION + NOTE: described here is what is implemented in Python 2.2.1 and later. In + Python 2.2, the :attr:`tp_init` of the type of the object returned by + :attr:`tp_new` was always called, if not *NULL*.) + + This field is inherited by subtypes. + + +.. c:member:: allocfunc PyTypeObject.tp_alloc + + An optional pointer to an instance allocation function. + + The function signature is :: + + PyObject *tp_alloc(PyTypeObject *self, Py_ssize_t nitems) + + The purpose of this function is to separate memory allocation from memory + initialization. It should return a pointer to a block of memory of adequate + length for the instance, suitably aligned, and initialized to zeros, but with + :attr:`ob_refcnt` set to ``1`` and :attr:`ob_type` set to the type argument. If + the type's :attr:`tp_itemsize` is non-zero, the object's :attr:`ob_size` field + should be initialized to *nitems* and the length of the allocated memory block + should be ``tp_basicsize + nitems*tp_itemsize``, rounded up to a multiple of + ``sizeof(void*)``; otherwise, *nitems* is not used and the length of the block + should be :attr:`tp_basicsize`. + + Do not use this function to do any other instance initialization, not even to + allocate additional memory; that should be done by :attr:`tp_new`. + + This field is inherited by static subtypes, but not by dynamic subtypes + (subtypes created by a class statement); in the latter, this field is always set + to :c:func:`PyType_GenericAlloc`, to force a standard heap allocation strategy. + That is also the recommended value for statically defined types. + + +.. c:member:: newfunc PyTypeObject.tp_new + + An optional pointer to an instance creation function. + + If this function is *NULL* for a particular type, that type cannot be called to + create new instances; presumably there is some other way to create instances, + like a factory function. + + The function signature is :: + + PyObject *tp_new(PyTypeObject *subtype, PyObject *args, PyObject *kwds) + + The subtype argument is the type of the object being created; the *args* and + *kwds* arguments represent positional and keyword arguments of the call to the + type. Note that subtype doesn't have to equal the type whose :attr:`tp_new` + function is called; it may be a subtype of that type (but not an unrelated + type). + + The :attr:`tp_new` function should call ``subtype->tp_alloc(subtype, nitems)`` + to allocate space for the object, and then do only as much further + initialization as is absolutely necessary. Initialization that can safely be + ignored or repeated should be placed in the :attr:`tp_init` handler. A good + rule of thumb is that for immutable types, all initialization should take place + in :attr:`tp_new`, while for mutable types, most initialization should be + deferred to :attr:`tp_init`. + + This field is inherited by subtypes, except it is not inherited by static types + whose :attr:`tp_base` is *NULL* or ``&PyBaseObject_Type``. The latter exception + is a precaution so that old extension types don't become callable simply by + being linked with Python 2.2. + + +.. c:member:: destructor PyTypeObject.tp_free + + An optional pointer to an instance deallocation function. + + The signature of this function has changed slightly: in Python 2.2 and 2.2.1, + its signature is :c:type:`destructor`:: + + void tp_free(PyObject *) + + In Python 2.3 and beyond, its signature is :c:type:`freefunc`:: + + void tp_free(void *) + + The only initializer that is compatible with both versions is ``_PyObject_Del``, + whose definition has suitably adapted in Python 2.3. + + This field is inherited by static subtypes, but not by dynamic subtypes + (subtypes created by a class statement); in the latter, this field is set to a + deallocator suitable to match :c:func:`PyType_GenericAlloc` and the value of the + :const:`Py_TPFLAGS_HAVE_GC` flag bit. + + +.. c:member:: inquiry PyTypeObject.tp_is_gc + + An optional pointer to a function called by the garbage collector. + + The garbage collector needs to know whether a particular object is collectible + or not. Normally, it is sufficient to look at the object's type's + :attr:`tp_flags` field, and check the :const:`Py_TPFLAGS_HAVE_GC` flag bit. But + some types have a mixture of statically and dynamically allocated instances, and + the statically allocated instances are not collectible. Such types should + define this function; it should return ``1`` for a collectible instance, and + ``0`` for a non-collectible instance. The signature is :: + + int tp_is_gc(PyObject *self) + + (The only example of this are types themselves. The metatype, + :c:data:`PyType_Type`, defines this function to distinguish between statically + and dynamically allocated types.) + + This field is inherited by subtypes. (VERSION NOTE: in Python 2.2, it was not + inherited. It is inherited in 2.2.1 and later versions.) + + +.. c:member:: PyObject* PyTypeObject.tp_bases + + Tuple of base types. + + This is set for types created by a class statement. It should be *NULL* for + statically defined types. + + This field is not inherited. + + +.. c:member:: PyObject* PyTypeObject.tp_mro + + Tuple containing the expanded set of base types, starting with the type itself + and ending with :class:`object`, in Method Resolution Order. + + This field is not inherited; it is calculated fresh by :c:func:`PyType_Ready`. + + +.. c:member:: PyObject* PyTypeObject.tp_cache + + Unused. Not inherited. Internal use only. + + +.. c:member:: PyObject* PyTypeObject.tp_subclasses + + List of weak references to subclasses. Not inherited. Internal use only. + + +.. c:member:: PyObject* PyTypeObject.tp_weaklist + + Weak reference list head, for weak references to this type object. Not + inherited. Internal use only. + +The remaining fields are only defined if the feature test macro +:const:`COUNT_ALLOCS` is defined, and are for internal use only. They are +documented here for completeness. None of these fields are inherited by +subtypes. + + +.. c:member:: Py_ssize_t PyTypeObject.tp_allocs + + Number of allocations. + + +.. c:member:: Py_ssize_t PyTypeObject.tp_frees + + Number of frees. + + +.. c:member:: Py_ssize_t PyTypeObject.tp_maxalloc + + Maximum simultaneously allocated objects. + + +.. c:member:: PyTypeObject* PyTypeObject.tp_next + + Pointer to the next type object with a non-zero :attr:`tp_allocs` field. + +Also, note that, in a garbage collected Python, tp_dealloc may be called from +any Python thread, not just the thread which created the object (if the object +becomes part of a refcount cycle, that cycle might be collected by a garbage +collection on any thread). This is not a problem for Python API calls, since +the thread on which tp_dealloc is called will own the Global Interpreter Lock +(GIL). However, if the object being destroyed in turn destroys objects from some +other C or C++ library, care should be taken to ensure that destroying those +objects on the thread which called tp_dealloc will not violate any assumptions +of the library. + + +.. _number-structs: + +Number Object Structures +======================== + +.. sectionauthor:: Amaury Forgeot d'Arc + + +.. c:type:: PyNumberMethods + + This structure holds pointers to the functions which an object uses to + implement the number protocol. Almost every function below is used by the + function of similar name documented in the :ref:`number` section. + + Here is the structure definition:: + + typedef struct { + binaryfunc nb_add; + binaryfunc nb_subtract; + binaryfunc nb_multiply; + binaryfunc nb_divide; + binaryfunc nb_remainder; + binaryfunc nb_divmod; + ternaryfunc nb_power; + unaryfunc nb_negative; + unaryfunc nb_positive; + unaryfunc nb_absolute; + inquiry nb_nonzero; /* Used by PyObject_IsTrue */ + unaryfunc nb_invert; + binaryfunc nb_lshift; + binaryfunc nb_rshift; + binaryfunc nb_and; + binaryfunc nb_xor; + binaryfunc nb_or; + coercion nb_coerce; /* Used by the coerce() function */ + unaryfunc nb_int; + unaryfunc nb_long; + unaryfunc nb_float; + unaryfunc nb_oct; + unaryfunc nb_hex; + + /* Added in release 2.0 */ + binaryfunc nb_inplace_add; + binaryfunc nb_inplace_subtract; + binaryfunc nb_inplace_multiply; + binaryfunc nb_inplace_divide; + binaryfunc nb_inplace_remainder; + ternaryfunc nb_inplace_power; + binaryfunc nb_inplace_lshift; + binaryfunc nb_inplace_rshift; + binaryfunc nb_inplace_and; + binaryfunc nb_inplace_xor; + binaryfunc nb_inplace_or; + + /* Added in release 2.2 */ + binaryfunc nb_floor_divide; + binaryfunc nb_true_divide; + binaryfunc nb_inplace_floor_divide; + binaryfunc nb_inplace_true_divide; + + /* Added in release 2.5 */ + unaryfunc nb_index; + } PyNumberMethods; + + +Binary and ternary functions may receive different kinds of arguments, depending +on the flag bit :const:`Py_TPFLAGS_CHECKTYPES`: + +- If :const:`Py_TPFLAGS_CHECKTYPES` is not set, the function arguments are + guaranteed to be of the object's type; the caller is responsible for calling + the coercion method specified by the :attr:`nb_coerce` member to convert the + arguments: + + .. c:member:: coercion PyNumberMethods.nb_coerce + + This function is used by :c:func:`PyNumber_CoerceEx` and has the same + signature. The first argument is always a pointer to an object of the + defined type. If the conversion to a common "larger" type is possible, the + function replaces the pointers with new references to the converted objects + and returns ``0``. If the conversion is not possible, the function returns + ``1``. If an error condition is set, it will return ``-1``. + +- If the :const:`Py_TPFLAGS_CHECKTYPES` flag is set, binary and ternary + functions must check the type of all their operands, and implement the + necessary conversions (at least one of the operands is an instance of the + defined type). This is the recommended way; with Python 3 coercion will + disappear completely. + +If the operation is not defined for the given operands, binary and ternary +functions must return ``Py_NotImplemented``, if another error occurred they must +return ``NULL`` and set an exception. + + +.. _mapping-structs: + +Mapping Object Structures +========================= + +.. sectionauthor:: Amaury Forgeot d'Arc + + +.. c:type:: PyMappingMethods + + This structure holds pointers to the functions which an object uses to + implement the mapping protocol. It has three members: + +.. c:member:: lenfunc PyMappingMethods.mp_length + + This function is used by :c:func:`PyMapping_Length` and + :c:func:`PyObject_Size`, and has the same signature. This slot may be set to + *NULL* if the object has no defined length. + +.. c:member:: binaryfunc PyMappingMethods.mp_subscript + + This function is used by :c:func:`PyObject_GetItem` and has the same + signature. This slot must be filled for the :c:func:`PyMapping_Check` + function to return ``1``, it can be *NULL* otherwise. + +.. c:member:: objobjargproc PyMappingMethods.mp_ass_subscript + + This function is used by :c:func:`PyObject_SetItem` and has the same + signature. If this slot is *NULL*, the object does not support item + assignment. + + +.. _sequence-structs: + +Sequence Object Structures +========================== + +.. sectionauthor:: Amaury Forgeot d'Arc + + +.. c:type:: PySequenceMethods + + This structure holds pointers to the functions which an object uses to + implement the sequence protocol. + +.. c:member:: lenfunc PySequenceMethods.sq_length + + This function is used by :c:func:`PySequence_Size` and :c:func:`PyObject_Size`, + and has the same signature. + +.. c:member:: binaryfunc PySequenceMethods.sq_concat + + This function is used by :c:func:`PySequence_Concat` and has the same + signature. It is also used by the ``+`` operator, after trying the numeric + addition via the :attr:`tp_as_number.nb_add` slot. + +.. c:member:: ssizeargfunc PySequenceMethods.sq_repeat + + This function is used by :c:func:`PySequence_Repeat` and has the same + signature. It is also used by the ``*`` operator, after trying numeric + multiplication via the :attr:`tp_as_number.nb_mul` slot. + +.. c:member:: ssizeargfunc PySequenceMethods.sq_item + + This function is used by :c:func:`PySequence_GetItem` and has the same + signature. This slot must be filled for the :c:func:`PySequence_Check` + function to return ``1``, it can be *NULL* otherwise. + + Negative indexes are handled as follows: if the :attr:`sq_length` slot is + filled, it is called and the sequence length is used to compute a positive + index which is passed to :attr:`sq_item`. If :attr:`sq_length` is *NULL*, + the index is passed as is to the function. + +.. c:member:: ssizeobjargproc PySequenceMethods.sq_ass_item + + This function is used by :c:func:`PySequence_SetItem` and has the same + signature. This slot may be left to *NULL* if the object does not support + item assignment. + +.. c:member:: objobjproc PySequenceMethods.sq_contains + + This function may be used by :c:func:`PySequence_Contains` and has the same + signature. This slot may be left to *NULL*, in this case + :c:func:`PySequence_Contains` simply traverses the sequence until it finds a + match. + +.. c:member:: binaryfunc PySequenceMethods.sq_inplace_concat + + This function is used by :c:func:`PySequence_InPlaceConcat` and has the same + signature. It should modify its first operand, and return it. + +.. c:member:: ssizeargfunc PySequenceMethods.sq_inplace_repeat + + This function is used by :c:func:`PySequence_InPlaceRepeat` and has the same + signature. It should modify its first operand, and return it. + +.. XXX need to explain precedence between mapping and sequence +.. XXX explains when to implement the sq_inplace_* slots + + +.. _buffer-structs: + +Buffer Object Structures +======================== + +.. sectionauthor:: Greg J. Stein <[email protected]> + + +The buffer interface exports a model where an object can expose its internal +data as a set of chunks of data, where each chunk is specified as a +pointer/length pair. These chunks are called :dfn:`segments` and are presumed +to be non-contiguous in memory. + +If an object does not export the buffer interface, then its :attr:`tp_as_buffer` +member in the :c:type:`PyTypeObject` structure should be *NULL*. Otherwise, the +:attr:`tp_as_buffer` will point to a :c:type:`PyBufferProcs` structure. + +.. note:: + + It is very important that your :c:type:`PyTypeObject` structure uses + :const:`Py_TPFLAGS_DEFAULT` for the value of the :attr:`tp_flags` member rather + than ``0``. This tells the Python runtime that your :c:type:`PyBufferProcs` + structure contains the :attr:`bf_getcharbuffer` slot. Older versions of Python + did not have this member, so a new Python interpreter using an old extension + needs to be able to test for its presence before using it. + + +.. c:type:: PyBufferProcs + + Structure used to hold the function pointers which define an implementation of + the buffer protocol. + + The first slot is :attr:`bf_getreadbuffer`, of type :c:type:`getreadbufferproc`. + If this slot is *NULL*, then the object does not support reading from the + internal data. This is non-sensical, so implementors should fill this in, but + callers should test that the slot contains a non-*NULL* value. + + The next slot is :attr:`bf_getwritebuffer` having type + :c:type:`getwritebufferproc`. This slot may be *NULL* if the object does not + allow writing into its returned buffers. + + The third slot is :attr:`bf_getsegcount`, with type :c:type:`getsegcountproc`. + This slot must not be *NULL* and is used to inform the caller how many segments + the object contains. Simple objects such as :c:type:`PyString_Type` and + :c:type:`PyBuffer_Type` objects contain a single segment. + + .. index:: single: PyType_HasFeature() + + The last slot is :attr:`bf_getcharbuffer`, of type :c:type:`getcharbufferproc`. + This slot will only be present if the :const:`Py_TPFLAGS_HAVE_GETCHARBUFFER` + flag is present in the :attr:`tp_flags` field of the object's + :c:type:`PyTypeObject`. Before using this slot, the caller should test whether it + is present by using the :c:func:`PyType_HasFeature` function. If the flag is + present, :attr:`bf_getcharbuffer` may be *NULL*, indicating that the object's + contents cannot be used as *8-bit characters*. The slot function may also raise + an error if the object's contents cannot be interpreted as 8-bit characters. + For example, if the object is an array which is configured to hold floating + point values, an exception may be raised if a caller attempts to use + :attr:`bf_getcharbuffer` to fetch a sequence of 8-bit characters. This notion of + exporting the internal buffers as "text" is used to distinguish between objects + that are binary in nature, and those which have character-based content. + + .. note:: + + The current policy seems to state that these characters may be multi-byte + characters. This implies that a buffer size of *N* does not mean there are *N* + characters present. + + +.. data:: Py_TPFLAGS_HAVE_GETCHARBUFFER + + Flag bit set in the type structure to indicate that the :attr:`bf_getcharbuffer` + slot is known. This being set does not indicate that the object supports the + buffer interface or that the :attr:`bf_getcharbuffer` slot is non-*NULL*. + + +.. c:type:: Py_ssize_t (*readbufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr) + + Return a pointer to a readable segment of the buffer in ``*ptrptr``. This + function is allowed to raise an exception, in which case it must return ``-1``. + The *segment* which is specified must be zero or positive, and strictly less + than the number of segments returned by the :attr:`bf_getsegcount` slot + function. On success, it returns the length of the segment, and sets + ``*ptrptr`` to a pointer to that memory. + + +.. c:type:: Py_ssize_t (*writebufferproc) (PyObject *self, Py_ssize_t segment, void **ptrptr) + + Return a pointer to a writable memory buffer in ``*ptrptr``, and the length of + that segment as the function return value. The memory buffer must correspond to + buffer segment *segment*. Must return ``-1`` and set an exception on error. + :exc:`TypeError` should be raised if the object only supports read-only buffers, + and :exc:`SystemError` should be raised when *segment* specifies a segment that + doesn't exist. + + .. Why doesn't it raise ValueError for this one? + GJS: because you shouldn't be calling it with an invalid + segment. That indicates a blatant programming error in the C code. + + +.. c:type:: Py_ssize_t (*segcountproc) (PyObject *self, Py_ssize_t *lenp) + + Return the number of memory segments which comprise the buffer. If *lenp* is + not *NULL*, the implementation must report the sum of the sizes (in bytes) of + all segments in ``*lenp``. The function cannot fail. + + +.. c:type:: Py_ssize_t (*charbufferproc) (PyObject *self, Py_ssize_t segment, const char **ptrptr) + + Return the size of the segment *segment* that *ptrptr* is set to. ``*ptrptr`` + is set to the memory buffer. Returns ``-1`` on error.
diff --git a/Python-2.7.5/Doc/c-api/unicode.rst b/Python-2.7.5/Doc/c-api/unicode.rst new file mode 100644 index 0000000..fd4fe23 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/unicode.rst
@@ -0,0 +1,1120 @@ +.. highlightlang:: c + +.. _unicodeobjects: + +Unicode Objects and Codecs +-------------------------- + +.. sectionauthor:: Marc-Andre Lemburg <[email protected]> + +Unicode Objects +^^^^^^^^^^^^^^^ + + +Unicode Type +"""""""""""" + +These are the basic Unicode object types used for the Unicode implementation in +Python: + + +.. c:type:: Py_UNICODE + + This type represents the storage type which is used by Python internally as + basis for holding Unicode ordinals. Python's default builds use a 16-bit type + for :c:type:`Py_UNICODE` and store Unicode values internally as UCS2. It is also + possible to build a UCS4 version of Python (most recent Linux distributions come + with UCS4 builds of Python). These builds then use a 32-bit type for + :c:type:`Py_UNICODE` and store Unicode data internally as UCS4. On platforms + where :c:type:`wchar_t` is available and compatible with the chosen Python + Unicode build variant, :c:type:`Py_UNICODE` is a typedef alias for + :c:type:`wchar_t` to enhance native platform compatibility. On all other + platforms, :c:type:`Py_UNICODE` is a typedef alias for either :c:type:`unsigned + short` (UCS2) or :c:type:`unsigned long` (UCS4). + +Note that UCS2 and UCS4 Python builds are not binary compatible. Please keep +this in mind when writing extensions or interfaces. + + +.. c:type:: PyUnicodeObject + + This subtype of :c:type:`PyObject` represents a Python Unicode object. + + +.. c:var:: PyTypeObject PyUnicode_Type + + This instance of :c:type:`PyTypeObject` represents the Python Unicode type. It + is exposed to Python code as ``unicode`` and ``types.UnicodeType``. + +The following APIs are really C macros and can be used to do fast checks and to +access internal read-only data of Unicode objects: + + +.. c:function:: int PyUnicode_Check(PyObject *o) + + Return true if the object *o* is a Unicode object or an instance of a Unicode + subtype. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + +.. c:function:: int PyUnicode_CheckExact(PyObject *o) + + Return true if the object *o* is a Unicode object, but not an instance of a + subtype. + + .. versionadded:: 2.2 + + +.. c:function:: Py_ssize_t PyUnicode_GET_SIZE(PyObject *o) + + Return the size of the object. *o* has to be a :c:type:`PyUnicodeObject` (not + checked). + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. c:function:: Py_ssize_t PyUnicode_GET_DATA_SIZE(PyObject *o) + + Return the size of the object's internal buffer in bytes. *o* has to be a + :c:type:`PyUnicodeObject` (not checked). + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. c:function:: Py_UNICODE* PyUnicode_AS_UNICODE(PyObject *o) + + Return a pointer to the internal :c:type:`Py_UNICODE` buffer of the object. *o* + has to be a :c:type:`PyUnicodeObject` (not checked). + + +.. c:function:: const char* PyUnicode_AS_DATA(PyObject *o) + + Return a pointer to the internal buffer of the object. *o* has to be a + :c:type:`PyUnicodeObject` (not checked). + + +.. c:function:: int PyUnicode_ClearFreeList() + + Clear the free list. Return the total number of freed items. + + .. versionadded:: 2.6 + + +Unicode Character Properties +"""""""""""""""""""""""""""" + +Unicode provides many different character properties. The most often needed ones +are available through these macros which are mapped to C functions depending on +the Python configuration. + + +.. c:function:: int Py_UNICODE_ISSPACE(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a whitespace character. + + +.. c:function:: int Py_UNICODE_ISLOWER(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a lowercase character. + + +.. c:function:: int Py_UNICODE_ISUPPER(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is an uppercase character. + + +.. c:function:: int Py_UNICODE_ISTITLE(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a titlecase character. + + +.. c:function:: int Py_UNICODE_ISLINEBREAK(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a linebreak character. + + +.. c:function:: int Py_UNICODE_ISDECIMAL(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a decimal character. + + +.. c:function:: int Py_UNICODE_ISDIGIT(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a digit character. + + +.. c:function:: int Py_UNICODE_ISNUMERIC(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is a numeric character. + + +.. c:function:: int Py_UNICODE_ISALPHA(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is an alphabetic character. + + +.. c:function:: int Py_UNICODE_ISALNUM(Py_UNICODE ch) + + Return 1 or 0 depending on whether *ch* is an alphanumeric character. + +These APIs can be used for fast direct character conversions: + + +.. c:function:: Py_UNICODE Py_UNICODE_TOLOWER(Py_UNICODE ch) + + Return the character *ch* converted to lower case. + + +.. c:function:: Py_UNICODE Py_UNICODE_TOUPPER(Py_UNICODE ch) + + Return the character *ch* converted to upper case. + + +.. c:function:: Py_UNICODE Py_UNICODE_TOTITLE(Py_UNICODE ch) + + Return the character *ch* converted to title case. + + +.. c:function:: int Py_UNICODE_TODECIMAL(Py_UNICODE ch) + + Return the character *ch* converted to a decimal positive integer. Return + ``-1`` if this is not possible. This macro does not raise exceptions. + + +.. c:function:: int Py_UNICODE_TODIGIT(Py_UNICODE ch) + + Return the character *ch* converted to a single digit integer. Return ``-1`` if + this is not possible. This macro does not raise exceptions. + + +.. c:function:: double Py_UNICODE_TONUMERIC(Py_UNICODE ch) + + Return the character *ch* converted to a double. Return ``-1.0`` if this is not + possible. This macro does not raise exceptions. + + +Plain Py_UNICODE +"""""""""""""""" + +To create Unicode objects and access their basic sequence properties, use these +APIs: + + +.. c:function:: PyObject* PyUnicode_FromUnicode(const Py_UNICODE *u, Py_ssize_t size) + + Create a Unicode object from the Py_UNICODE buffer *u* of the given size. *u* + may be *NULL* which causes the contents to be undefined. It is the user's + responsibility to fill in the needed data. The buffer is copied into the new + object. If the buffer is not *NULL*, the return value might be a shared object. + Therefore, modification of the resulting Unicode object is only allowed when *u* + is *NULL*. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_FromStringAndSize(const char *u, Py_ssize_t size) + + Create a Unicode object from the char buffer *u*. The bytes will be interpreted + as being UTF-8 encoded. *u* may also be *NULL* which + causes the contents to be undefined. It is the user's responsibility to fill in + the needed data. The buffer is copied into the new object. If the buffer is not + *NULL*, the return value might be a shared object. Therefore, modification of + the resulting Unicode object is only allowed when *u* is *NULL*. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject *PyUnicode_FromString(const char *u) + + Create a Unicode object from an UTF-8 encoded null-terminated char buffer + *u*. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyUnicode_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 unicode string and return + a string 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: + + .. % 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 character, | + | | | represented as an 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. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%U` | PyObject\* | A unicode object. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%V` | PyObject\*, char \* | A unicode object (which may be | + | | | *NULL*) and a null-terminated | + | | | C character array as a second | + | | | parameter (which will be used, | + | | | if the first parameter is | + | | | *NULL*). | + +-------------------+---------------------+--------------------------------+ + | :attr:`%S` | PyObject\* | The result of calling | + | | | :func:`PyObject_Unicode`. | + +-------------------+---------------------+--------------------------------+ + | :attr:`%R` | PyObject\* | The result of calling | + | | | :func:`PyObject_Repr`. | + +-------------------+---------------------+--------------------------------+ + + An unrecognized format character causes all the rest of the format string to be + copied as-is to the result string, and any extra arguments discarded. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyUnicode_FromFormatV(const char *format, va_list vargs) + + Identical to :func:`PyUnicode_FromFormat` except that it takes exactly two + arguments. + + .. versionadded:: 2.6 + + +.. c:function:: Py_UNICODE* PyUnicode_AsUnicode(PyObject *unicode) + + Return a read-only pointer to the Unicode object's internal + :c:type:`Py_UNICODE` buffer, *NULL* if *unicode* is not a Unicode object. + Note that the resulting :c:type:`Py_UNICODE*` string may contain embedded + null characters, which would cause the string to be truncated when used in + most C functions. + + +.. c:function:: Py_ssize_t PyUnicode_GetSize(PyObject *unicode) + + Return the length of the Unicode object. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type. This might require changes + in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_FromEncodedObject(PyObject *obj, const char *encoding, const char *errors) + + Coerce an encoded object *obj* to an Unicode object and return a reference with + incremented refcount. + + String and other char buffer compatible objects are decoded according to the + given encoding and using the error handling defined by errors. Both can be + *NULL* to have the interface use the default values (see the next section for + details). + + All other objects, including Unicode objects, cause a :exc:`TypeError` to be + set. + + The API returns *NULL* if there was an error. The caller is responsible for + decref'ing the returned objects. + + +.. c:function:: PyObject* PyUnicode_FromObject(PyObject *obj) + + Shortcut for ``PyUnicode_FromEncodedObject(obj, NULL, "strict")`` which is used + throughout the interpreter whenever coercion to Unicode is needed. + +If the platform supports :c:type:`wchar_t` and provides a header file wchar.h, +Python can interface directly to this type using the following functions. +Support is optimized if Python's own :c:type:`Py_UNICODE` type is identical to +the system's :c:type:`wchar_t`. + + +wchar_t Support +""""""""""""""" + +:c:type:`wchar_t` support for platforms which support it: + +.. c:function:: PyObject* PyUnicode_FromWideChar(const wchar_t *w, Py_ssize_t size) + + Create a Unicode object from the :c:type:`wchar_t` buffer *w* of the given *size*. + Return *NULL* on failure. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: Py_ssize_t PyUnicode_AsWideChar(PyUnicodeObject *unicode, wchar_t *w, Py_ssize_t size) + + Copy the Unicode object contents into the :c:type:`wchar_t` buffer *w*. At most + *size* :c:type:`wchar_t` characters are copied (excluding a possibly trailing + 0-termination character). Return the number of :c:type:`wchar_t` characters + copied or -1 in case of an error. Note that the resulting :c:type:`wchar_t` + string may or may not be 0-terminated. It is the responsibility of the caller + to make sure that the :c:type:`wchar_t` string is 0-terminated in case this is + required by the application. Also, note that the :c:type:`wchar_t*` string + might contain null characters, which would cause the string to be truncated + when used with most C functions. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type and used an :c:type:`int` + type for *size*. This might require changes in your code for properly + supporting 64-bit systems. + + +.. _builtincodecs: + +Built-in Codecs +^^^^^^^^^^^^^^^ + +Python provides a set of built-in codecs which are written in C for speed. All of +these codecs are directly usable via the following functions. + +Many of the following APIs take two arguments encoding and errors, and they +have the same semantics as the ones of the built-in :func:`unicode` Unicode +object constructor. + +Setting encoding to *NULL* causes the default encoding to be used which is +ASCII. The file system calls should use :c:data:`Py_FileSystemDefaultEncoding` +as the encoding for file names. This variable should be treated as read-only: on +some systems, it will be a pointer to a static string, on others, it will change +at run-time (such as when the application invokes setlocale). + +Error handling is set by errors which may also be set to *NULL* meaning to use +the default handling defined for the codec. Default error handling for all +built-in codecs is "strict" (:exc:`ValueError` is raised). + +The codecs all use a similar interface. Only deviation from the following +generic ones are documented for simplicity. + + +Generic Codecs +"""""""""""""" + +These are the generic codec APIs: + + +.. c:function:: PyObject* PyUnicode_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) + + Create a Unicode object by decoding *size* bytes of the encoded string *s*. + *encoding* and *errors* have the same meaning as the parameters of the same name + in the :func:`unicode` built-in function. The codec to be used is looked up + using the Python codec registry. Return *NULL* if an exception was raised by + the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_Encode(const Py_UNICODE *s, Py_ssize_t size, const char *encoding, const char *errors) + + Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* and return a Python + string object. *encoding* and *errors* have the same meaning as the parameters + of the same name in the Unicode :meth:`encode` method. The codec to be used is + looked up using the Python codec registry. Return *NULL* if an exception was + raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_AsEncodedString(PyObject *unicode, const char *encoding, const char *errors) + + Encode a Unicode object and return the result as Python string object. + *encoding* and *errors* have the same meaning as the parameters of the same name + in the Unicode :meth:`encode` method. The codec to be used is looked up using + the Python codec registry. Return *NULL* if an exception was raised by the + codec. + + +UTF-8 Codecs +"""""""""""" + +These are the UTF-8 codec APIs: + + +.. c:function:: PyObject* PyUnicode_DecodeUTF8(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the UTF-8 encoded string + *s*. Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_DecodeUTF8Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed) + + If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF8`. If + *consumed* is not *NULL*, trailing incomplete UTF-8 byte sequences will not be + treated as an error. Those bytes will not be decoded and the number of bytes + that have been decoded will be stored in *consumed*. + + .. versionadded:: 2.4 + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_EncodeUTF8(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :c:type:`Py_UNICODE` buffer *s* of the given *size* using UTF-8 and return a + Python string object. Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_AsUTF8String(PyObject *unicode) + + Encode a Unicode object using UTF-8 and return the result as Python string + object. Error handling is "strict". Return *NULL* if an exception was raised + by the codec. + + +UTF-32 Codecs +""""""""""""" + +These are the UTF-32 codec APIs: + + +.. c:function:: PyObject* PyUnicode_DecodeUTF32(const char *s, Py_ssize_t size, const char *errors, int *byteorder) + + Decode *size* bytes from a UTF-32 encoded buffer string and return the + corresponding Unicode object. *errors* (if non-*NULL*) defines the error + handling. It defaults to "strict". + + If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte + order:: + + *byteorder == -1: little endian + *byteorder == 0: native order + *byteorder == 1: big endian + + If ``*byteorder`` is zero, and the first four bytes of the input data are a + byte order mark (BOM), the decoder switches to this byte order and the BOM is + not copied into the resulting Unicode string. If ``*byteorder`` is ``-1`` or + ``1``, any byte order mark is copied to the output. + + After completion, *\*byteorder* is set to the current byte order at the end + of input data. + + In a narrow build codepoints outside the BMP will be decoded as surrogate pairs. + + If *byteorder* is *NULL*, the codec starts in native order mode. + + Return *NULL* if an exception was raised by the codec. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyUnicode_DecodeUTF32Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed) + + If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF32`. If + *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF32Stateful` will not treat + trailing incomplete UTF-32 byte sequences (such as a number of bytes not divisible + by four) as an error. Those bytes will not be decoded and the number of bytes + that have been decoded will be stored in *consumed*. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyUnicode_EncodeUTF32(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder) + + Return a Python bytes object holding the UTF-32 encoded value of the Unicode + data in *s*. Output is written according to the following byte order:: + + byteorder == -1: little endian + byteorder == 0: native byte order (writes a BOM mark) + byteorder == 1: big endian + + If byteorder is ``0``, the output string will always start with the Unicode BOM + mark (U+FEFF). In the other two modes, no BOM mark is prepended. + + If *Py_UNICODE_WIDE* is not defined, surrogate pairs will be output + as a single codepoint. + + Return *NULL* if an exception was raised by the codec. + + .. versionadded:: 2.6 + + +.. c:function:: PyObject* PyUnicode_AsUTF32String(PyObject *unicode) + + Return a Python string using the UTF-32 encoding in native byte order. The + string always starts with a BOM mark. Error handling is "strict". Return + *NULL* if an exception was raised by the codec. + + .. versionadded:: 2.6 + + +UTF-16 Codecs +""""""""""""" + +These are the UTF-16 codec APIs: + + +.. c:function:: PyObject* PyUnicode_DecodeUTF16(const char *s, Py_ssize_t size, const char *errors, int *byteorder) + + Decode *size* bytes from a UTF-16 encoded buffer string and return the + corresponding Unicode object. *errors* (if non-*NULL*) defines the error + handling. It defaults to "strict". + + If *byteorder* is non-*NULL*, the decoder starts decoding using the given byte + order:: + + *byteorder == -1: little endian + *byteorder == 0: native order + *byteorder == 1: big endian + + If ``*byteorder`` is zero, and the first two bytes of the input data are a + byte order mark (BOM), the decoder switches to this byte order and the BOM is + not copied into the resulting Unicode string. If ``*byteorder`` is ``-1`` or + ``1``, any byte order mark is copied to the output (where it will result in + either a ``\ufeff`` or a ``\ufffe`` character). + + After completion, *\*byteorder* is set to the current byte order at the end + of input data. + + If *byteorder* is *NULL*, the codec starts in native order mode. + + Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_DecodeUTF16Stateful(const char *s, Py_ssize_t size, const char *errors, int *byteorder, Py_ssize_t *consumed) + + If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF16`. If + *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeUTF16Stateful` will not treat + trailing incomplete UTF-16 byte sequences (such as an odd number of bytes or a + split surrogate pair) as an error. Those bytes will not be decoded and the + number of bytes that have been decoded will be stored in *consumed*. + + .. versionadded:: 2.4 + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size* and an :c:type:`int *` + type for *consumed*. This might require changes in your code for + properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_EncodeUTF16(const Py_UNICODE *s, Py_ssize_t size, const char *errors, int byteorder) + + Return a Python string object holding the UTF-16 encoded value of the Unicode + data in *s*. Output is written according to the following byte order:: + + byteorder == -1: little endian + byteorder == 0: native byte order (writes a BOM mark) + byteorder == 1: big endian + + If byteorder is ``0``, the output string will always start with the Unicode BOM + mark (U+FEFF). In the other two modes, no BOM mark is prepended. + + If *Py_UNICODE_WIDE* is defined, a single :c:type:`Py_UNICODE` value may get + represented as a surrogate pair. If it is not defined, each :c:type:`Py_UNICODE` + values is interpreted as an UCS-2 character. + + Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_AsUTF16String(PyObject *unicode) + + Return a Python string using the UTF-16 encoding in native byte order. The + string always starts with a BOM mark. Error handling is "strict". Return + *NULL* if an exception was raised by the codec. + + +UTF-7 Codecs +"""""""""""" + +These are the UTF-7 codec APIs: + + +.. c:function:: PyObject* PyUnicode_DecodeUTF7(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the UTF-7 encoded string + *s*. Return *NULL* if an exception was raised by the codec. + + +.. c:function:: PyObject* PyUnicode_DecodeUTF7Stateful(const char *s, Py_ssize_t size, const char *errors, Py_ssize_t *consumed) + + If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeUTF7`. If + *consumed* is not *NULL*, trailing incomplete UTF-7 base-64 sections will not + be treated as an error. Those bytes will not be decoded and the number of + bytes that have been decoded will be stored in *consumed*. + + +.. c:function:: PyObject* PyUnicode_EncodeUTF7(const Py_UNICODE *s, Py_ssize_t size, int base64SetO, int base64WhiteSpace, const char *errors) + + Encode the :c:type:`Py_UNICODE` buffer of the given size using UTF-7 and + return a Python bytes object. Return *NULL* if an exception was raised by + the codec. + + If *base64SetO* is nonzero, "Set O" (punctuation that has no otherwise + special meaning) will be encoded in base-64. If *base64WhiteSpace* is + nonzero, whitespace will be encoded in base-64. Both are set to zero for the + Python "utf-7" codec. + + +Unicode-Escape Codecs +""""""""""""""""""""" + +These are the "Unicode Escape" codec APIs: + + +.. c:function:: PyObject* PyUnicode_DecodeUnicodeEscape(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the Unicode-Escape encoded + string *s*. Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_EncodeUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size) + + Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Unicode-Escape and + return a Python string object. Return *NULL* if an exception was raised by the + codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_AsUnicodeEscapeString(PyObject *unicode) + + Encode a Unicode object using Unicode-Escape and return the result as Python + string object. Error handling is "strict". Return *NULL* if an exception was + raised by the codec. + + +Raw-Unicode-Escape Codecs +""""""""""""""""""""""""" + +These are the "Raw Unicode Escape" codec APIs: + + +.. c:function:: PyObject* PyUnicode_DecodeRawUnicodeEscape(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the Raw-Unicode-Escape + encoded string *s*. Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_EncodeRawUnicodeEscape(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Raw-Unicode-Escape + and return a Python string object. Return *NULL* if an exception was raised by + the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_AsRawUnicodeEscapeString(PyObject *unicode) + + Encode a Unicode object using Raw-Unicode-Escape and return the result as + Python string object. Error handling is "strict". Return *NULL* if an exception + was raised by the codec. + + +Latin-1 Codecs +"""""""""""""" + +These are the Latin-1 codec APIs: Latin-1 corresponds to the first 256 Unicode +ordinals and only these are accepted by the codecs during encoding. + + +.. c:function:: PyObject* PyUnicode_DecodeLatin1(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the Latin-1 encoded string + *s*. Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_EncodeLatin1(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :c:type:`Py_UNICODE` buffer of the given *size* using Latin-1 and return + a Python string object. Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_AsLatin1String(PyObject *unicode) + + Encode a Unicode object using Latin-1 and return the result as Python string + object. Error handling is "strict". Return *NULL* if an exception was raised + by the codec. + + +ASCII Codecs +"""""""""""" + +These are the ASCII codec APIs. Only 7-bit ASCII data is accepted. All other +codes generate errors. + + +.. c:function:: PyObject* PyUnicode_DecodeASCII(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the ASCII encoded string + *s*. Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_EncodeASCII(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :c:type:`Py_UNICODE` buffer of the given *size* using ASCII and return a + Python string object. Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_AsASCIIString(PyObject *unicode) + + Encode a Unicode object using ASCII and return the result as Python string + object. Error handling is "strict". Return *NULL* if an exception was raised + by the codec. + + +Character Map Codecs +"""""""""""""""""""" + +This codec is special in that it can be used to implement many different codecs +(and this is in fact what was done to obtain most of the standard codecs +included in the :mod:`encodings` package). The codec uses mapping to encode and +decode characters. + +Decoding mappings must map single string characters to single Unicode +characters, integers (which are then interpreted as Unicode ordinals) or None +(meaning "undefined mapping" and causing an error). + +Encoding mappings must map single Unicode characters to single string +characters, integers (which are then interpreted as Latin-1 ordinals) or None +(meaning "undefined mapping" and causing an error). + +The mapping objects provided must only support the __getitem__ mapping +interface. + +If a character lookup fails with a LookupError, the character is copied as-is +meaning that its ordinal value will be interpreted as Unicode or Latin-1 ordinal +resp. Because of this, mappings only need to contain those mappings which map +characters to different code points. + +These are the mapping codec APIs: + +.. c:function:: PyObject* PyUnicode_DecodeCharmap(const char *s, Py_ssize_t size, PyObject *mapping, const char *errors) + + Create a Unicode object by decoding *size* bytes of the encoded string *s* using + the given *mapping* object. Return *NULL* if an exception was raised by the + codec. If *mapping* is *NULL* latin-1 decoding will be done. Else it can be a + dictionary mapping byte or a unicode string, which is treated as a lookup table. + Byte values greater that the length of the string and U+FFFE "characters" are + treated as "undefined mapping". + + .. versionchanged:: 2.4 + Allowed unicode string as mapping argument. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_EncodeCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *mapping, const char *errors) + + Encode the :c:type:`Py_UNICODE` buffer of the given *size* using the given + *mapping* object and return a Python string object. Return *NULL* if an + exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_AsCharmapString(PyObject *unicode, PyObject *mapping) + + Encode a Unicode object using the given *mapping* object and return the result + as Python string object. Error handling is "strict". Return *NULL* if an + exception was raised by the codec. + +The following codec API is special in that maps Unicode to Unicode. + + +.. c:function:: PyObject* PyUnicode_TranslateCharmap(const Py_UNICODE *s, Py_ssize_t size, PyObject *table, const char *errors) + + Translate a :c:type:`Py_UNICODE` buffer of the given *size* by applying a + character mapping *table* to it and return the resulting Unicode object. Return + *NULL* when an exception was raised by the codec. + + The *mapping* table must map Unicode ordinal integers to Unicode ordinal + integers or None (causing deletion of the character). + + Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries + and sequences work well. Unmapped character ordinals (ones which cause a + :exc:`LookupError`) are left untouched and are copied as-is. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +MBCS codecs for Windows +""""""""""""""""""""""" + +These are the MBCS codec APIs. They are currently only available on Windows and +use the Win32 MBCS converters to implement the conversions. Note that MBCS (or +DBCS) is a class of encodings, not just one. The target encoding is defined by +the user settings on the machine running the codec. + + +.. c:function:: PyObject* PyUnicode_DecodeMBCS(const char *s, Py_ssize_t size, const char *errors) + + Create a Unicode object by decoding *size* bytes of the MBCS encoded string *s*. + Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_DecodeMBCSStateful(const char *s, int size, const char *errors, int *consumed) + + If *consumed* is *NULL*, behave like :c:func:`PyUnicode_DecodeMBCS`. If + *consumed* is not *NULL*, :c:func:`PyUnicode_DecodeMBCSStateful` will not decode + trailing lead byte and the number of bytes that have been decoded will be stored + in *consumed*. + + .. versionadded:: 2.5 + + +.. c:function:: PyObject* PyUnicode_EncodeMBCS(const Py_UNICODE *s, Py_ssize_t size, const char *errors) + + Encode the :c:type:`Py_UNICODE` buffer of the given *size* using MBCS and return a + Python string object. Return *NULL* if an exception was raised by the codec. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *size*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_AsMBCSString(PyObject *unicode) + + Encode a Unicode object using MBCS and return the result as Python string + object. Error handling is "strict". Return *NULL* if an exception was raised + by the codec. + + +Methods & Slots +""""""""""""""" + +.. _unicodemethodsandslots: + +Methods and Slot Functions +^^^^^^^^^^^^^^^^^^^^^^^^^^ + +The following APIs are capable of handling Unicode objects and strings on input +(we refer to them as strings in the descriptions) and return Unicode objects or +integers as appropriate. + +They all return *NULL* or ``-1`` if an exception occurs. + + +.. c:function:: PyObject* PyUnicode_Concat(PyObject *left, PyObject *right) + + Concat two strings giving a new Unicode string. + + +.. c:function:: PyObject* PyUnicode_Split(PyObject *s, PyObject *sep, Py_ssize_t maxsplit) + + Split a string giving a list of Unicode strings. If *sep* is *NULL*, splitting + will be done at all whitespace substrings. Otherwise, splits occur at the given + separator. At most *maxsplit* splits will be done. If negative, no limit is + set. Separators are not included in the resulting list. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *maxsplit*. This might require + changes in your code for properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_Splitlines(PyObject *s, int keepend) + + Split a Unicode string at line breaks, returning a list of Unicode strings. + CRLF is considered to be one line break. If *keepend* is 0, the Line break + characters are not included in the resulting strings. + + +.. c:function:: PyObject* PyUnicode_Translate(PyObject *str, PyObject *table, const char *errors) + + Translate a string by applying a character mapping table to it and return the + resulting Unicode object. + + The mapping table must map Unicode ordinal integers to Unicode ordinal integers + or None (causing deletion of the character). + + Mapping tables need only provide the :meth:`__getitem__` interface; dictionaries + and sequences work well. Unmapped character ordinals (ones which cause a + :exc:`LookupError`) are left untouched and are copied as-is. + + *errors* has the usual meaning for codecs. It may be *NULL* which indicates to + use the default error handling. + + +.. c:function:: PyObject* PyUnicode_Join(PyObject *separator, PyObject *seq) + + Join a sequence of strings using the given *separator* and return the resulting + Unicode string. + + +.. c:function:: int PyUnicode_Tailmatch(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction) + + Return 1 if *substr* matches ``str[start:end]`` at the given tail end + (*direction* == -1 means to do a prefix match, *direction* == 1 a suffix match), + 0 otherwise. Return ``-1`` if an error occurred. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *start* and *end*. This + might require changes in your code for properly supporting 64-bit + systems. + + +.. c:function:: Py_ssize_t PyUnicode_Find(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end, int direction) + + Return the first position of *substr* in ``str[start:end]`` using the given + *direction* (*direction* == 1 means to do a forward search, *direction* == -1 a + backward search). The return value is the index of the first match; a value of + ``-1`` indicates that no match was found, and ``-2`` indicates that an error + occurred and an exception has been set. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *start* and *end*. This + might require changes in your code for properly supporting 64-bit + systems. + + +.. c:function:: Py_ssize_t PyUnicode_Count(PyObject *str, PyObject *substr, Py_ssize_t start, Py_ssize_t end) + + Return the number of non-overlapping occurrences of *substr* in + ``str[start:end]``. Return ``-1`` if an error occurred. + + .. versionchanged:: 2.5 + This function returned an :c:type:`int` type and used an :c:type:`int` + type for *start* and *end*. This might require changes in your code for + properly supporting 64-bit systems. + + +.. c:function:: PyObject* PyUnicode_Replace(PyObject *str, PyObject *substr, PyObject *replstr, Py_ssize_t maxcount) + + Replace at most *maxcount* occurrences of *substr* in *str* with *replstr* and + return the resulting Unicode object. *maxcount* == -1 means replace all + occurrences. + + .. versionchanged:: 2.5 + This function used an :c:type:`int` type for *maxcount*. This might + require changes in your code for properly supporting 64-bit systems. + + +.. c:function:: int PyUnicode_Compare(PyObject *left, PyObject *right) + + Compare two strings and return -1, 0, 1 for less than, equal, and greater than, + respectively. + + +.. c:function:: int PyUnicode_RichCompare(PyObject *left, PyObject *right, int op) + + Rich compare two unicode strings and return one of the following: + + * ``NULL`` in case an exception was raised + * :const:`Py_True` or :const:`Py_False` for successful comparisons + * :const:`Py_NotImplemented` in case the type combination is unknown + + Note that :const:`Py_EQ` and :const:`Py_NE` comparisons can cause a + :exc:`UnicodeWarning` in case the conversion of the arguments to Unicode fails + with a :exc:`UnicodeDecodeError`. + + Possible values for *op* are :const:`Py_GT`, :const:`Py_GE`, :const:`Py_EQ`, + :const:`Py_NE`, :const:`Py_LT`, and :const:`Py_LE`. + + +.. c:function:: PyObject* PyUnicode_Format(PyObject *format, PyObject *args) + + Return a new string object from *format* and *args*; this is analogous to + ``format % args``. The *args* argument must be a tuple. + + +.. c:function:: int PyUnicode_Contains(PyObject *container, PyObject *element) + + Check whether *element* is contained in *container* and return true or false + accordingly. + + *element* has to coerce to a one element Unicode string. ``-1`` is returned if + there was an error.
diff --git a/Python-2.7.5/Doc/c-api/utilities.rst b/Python-2.7.5/Doc/c-api/utilities.rst new file mode 100644 index 0000000..f43933b --- /dev/null +++ b/Python-2.7.5/Doc/c-api/utilities.rst
@@ -0,0 +1,22 @@ +.. 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
diff --git a/Python-2.7.5/Doc/c-api/veryhigh.rst b/Python-2.7.5/Doc/c-api/veryhigh.rst new file mode 100644 index 0000000..4ce3b03 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/veryhigh.rst
@@ -0,0 +1,323 @@ +.. 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, char **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. 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 (ie, 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`. 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_SimpleFileFlags(FILE *fp, const char *filename, PyCompilerFlags *flags) + + This is a simplified interface to :c:func:`PyRun_SimpleFileExFlags` below, + leaving *closeit* set to ``0``. + + +.. 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. 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``. 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``. Returns ``0`` at EOF. + + +.. 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. + + +.. 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 + dictionaries *globals* and *locals* with the compiler flags specified by + *flags*. 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. + 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) + + 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. + + +.. c:function:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals) + + This is a simplified interface to :c:func:`PyEval_EvalCodeEx`, with just + the code object, and the dictionaries of global and local variables. + The other arguments are set to *NULL*. + + +.. c:function:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure) + + Evaluate a precompiled code object, given a particular environment for its + evaluation. This environment consists of dictionaries of global and local + variables, arrays of arguments, keywords and defaults, and a closure tuple of + cells. + + +.. c:function:: PyObject* PyEval_EvalFrame(PyFrameObject *f) + + Evaluate an execution frame. This is a simplified interface to + 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:`throw` methods of generator objects. + + +.. 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`. +
diff --git a/Python-2.7.5/Doc/c-api/weakref.rst b/Python-2.7.5/Doc/c-api/weakref.rst new file mode 100644 index 0000000..243cfd1 --- /dev/null +++ b/Python-2.7.5/Doc/c-api/weakref.rst
@@ -0,0 +1,83 @@ +.. 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. + + .. versionadded:: 2.2 + + +.. c:function:: int PyWeakref_CheckRef(ob) + + Return true if *ob* is a reference object. + + .. versionadded:: 2.2 + + +.. c:function:: int PyWeakref_CheckProxy(ob) + + Return true if *ob* is a proxy object. + + .. versionadded:: 2.2 + + +.. 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`. + + .. versionadded:: 2.2 + + +.. 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`. + + .. versionadded:: 2.2 + + +.. 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`. + + .. versionadded:: 2.2 + + .. warning:: + + 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. + + .. versionadded:: 2.2