Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Make so small IronPython-specific changes to the documentation.

Remove the c-api docs and replace them with the .NET api docs.

Add the IronPython license information.
  • Loading branch information...
commit 0c3d1db5488c45b6edb284feb29050e3f50f9b1b 1 parent 6a63d45
@jdhardy jdhardy authored
Showing with 183 additions and 12,805 deletions.
  1. +0 −26 c-api/abstract.rst
  2. +0 −122 c-api/allocation.rst
  3. +0 −559 c-api/arg.rst
  4. +0 −54 c-api/bool.rst
  5. +0 −450 c-api/buffer.rst
  6. +0 −87 c-api/bytearray.rst
  7. +0 −150 c-api/capsule.rst
  8. +0 −62 c-api/cell.rst
  9. +0 −65 c-api/class.rst
  10. +0 −59 c-api/cobject.rst
  11. +0 −50 c-api/code.rst
  12. +0 −118 c-api/codec.rst
  13. +0 −132 c-api/complex.rst
  14. +0 −109 c-api/concrete.rst
  15. +0 −181 c-api/conversion.rst
  16. +0 −239 c-api/datetime.rst
  17. +0 −55 c-api/descriptor.rst
  18. +0 −233 c-api/dict.rst
  19. +0 −621 c-api/exceptions.rst
  20. +0 −178 c-api/file.rst
  21. +0 −118 c-api/float.rst
  22. +0 −83 c-api/function.rst
  23. +0 −165 c-api/gcsupport.rst
  24. +0 −38 c-api/gen.rst
  25. +0 −276 c-api/import.rst
  26. +0 −27 c-api/index.rst
  27. +0 −1,135 c-api/init.rst
  28. +0 −139 c-api/int.rst
  29. +0 −636 c-api/intro.rst
  30. +0 −50 c-api/iter.rst
  31. +0 −62 c-api/iterator.rst
  32. +0 −189 c-api/list.rst
  33. +0 −278 c-api/long.rst
  34. +0 −83 c-api/mapping.rst
  35. +0 −100 c-api/marshal.rst
  36. +0 −209 c-api/memory.rst
  37. +0 −72 c-api/method.rst
  38. +0 −121 c-api/module.rst
  39. +0 −28 c-api/none.rst
  40. +0 −322 c-api/number.rst
  41. +0 −66 c-api/objbuffer.rst
  42. +0 −402 c-api/object.rst
  43. +0 −18 c-api/objimpl.rst
  44. +0 −74 c-api/refcounting.rst
  45. +0 −55 c-api/reflection.rst
  46. +0 −218 c-api/sequence.rst
  47. +0 −175 c-api/set.rst
  48. +0 −68 c-api/slice.rst
  49. +0 −333 c-api/string.rst
  50. +0 −298 c-api/structures.rst
  51. +0 −151 c-api/sys.rst
  52. +0 −164 c-api/tuple.rst
  53. +0 −96 c-api/type.rst
  54. +0 −1,448 c-api/typeobj.rst
  55. +0 −1,113 c-api/unicode.rst
  56. +0 −22 c-api/utilities.rst
  57. +0 −323 c-api/veryhigh.rst
  58. +0 −83 c-api/weakref.rst
  59. +6 −10 conf.py
  60. +4 −4 contents.rst
  61. +6 −0 copyright.rst
  62. +2 −2 glossary.rst
  63. +94 −1 license.rst
  64. +16 −0 net-api/extending.rst
  65. +16 −0 net-api/index.rst
  66. +39 −0 net-api/parsing.rst
View
26 c-api/abstract.rst
@@ -1,26 +0,0 @@
-.. 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 :cfunc:`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
View
122 c-api/allocation.rst
@@ -1,122 +0,0 @@
-.. highlightlang:: c
-
-.. _allocating-objects:
-
-Allocating Objects on the Heap
-==============================
-
-
-.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)
-
-
-.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
-
- .. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
- changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: void _PyObject_Del(PyObject *op)
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
-
- This does everything :cfunc:`PyObject_Init` does, and also initializes the
- length information for a variable-size object.
-
- .. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
- changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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 :ctype:`int` type for *size*. This might require
- changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: void PyObject_Del(PyObject *op)
-
- Releases memory allocated to an object using :cfunc:`PyObject_New` or
- :cfunc:`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.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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
- :cfunc:`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.
-
-
-.. cvar:: 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.
View
559 c-api/arg.rst
@@ -1,559 +0,0 @@
-.. 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, :cfunc:`PyArg_ParseTuple`,
-:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`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.
-
-``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 :ctype:`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 :cmacro:`PY_SSIZE_T_CLEAN` before including
- :file:`Python.h`. If the macro is defined, length is a :ctype:`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 :ctype:`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
- :ctype:`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 :ctype:`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 :ctype:`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.
-
- :cfunc:`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
- :cfunc:`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 :ctype:`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 :ctype:`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 :cfunc:`PyMem_Free` to free the allocated buffer
- after usage.
-
- If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),
- :cfunc:`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
- :ctype:`unsigned char`.
-
-``B`` (integer) [unsigned char]
- Convert a Python integer to a tiny int without overflow checking, stored in
- a C :ctype:`unsigned char`.
-
- .. versionadded:: 2.3
-
-``h`` (integer) [short int]
- Convert a Python integer to a C :ctype:`short int`.
-
-``H`` (integer) [unsigned short int]
- Convert a Python integer to a C :ctype:`unsigned short int`, without
- overflow checking.
-
- .. versionadded:: 2.3
-
-``i`` (integer) [int]
- Convert a Python integer to a plain C :ctype:`int`.
-
-``I`` (integer) [unsigned int]
- Convert a Python integer to a C :ctype:`unsigned int`, without overflow
- checking.
-
- .. versionadded:: 2.3
-
-``l`` (integer) [long int]
- Convert a Python integer to a C :ctype:`long int`.
-
-``k`` (integer) [unsigned long]
- Convert a Python integer or long integer to a C :ctype:`unsigned long`
- without overflow checking.
-
- .. versionadded:: 2.3
-
-``L`` (integer) [PY_LONG_LONG]
- Convert a Python integer to a C :ctype:`long long`. This format is only
- available on platforms that support :ctype:`long long` (or :ctype:`_int64`
- on Windows).
-
-``K`` (integer) [unsigned PY_LONG_LONG]
- Convert a Python integer or long integer to a C :ctype:`unsigned long long`
- without overflow checking. This format is only available on platforms that
- support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on
- Windows).
-
- .. versionadded:: 2.3
-
-``n`` (integer) [Py_ssize_t]
- Convert a Python integer or long integer to a C :ctype:`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
- :ctype:`char`.
-
-``f`` (float) [float]
- Convert a Python floating point number to a C :ctype:`float`.
-
-``d`` (float) [double]
- Convert a Python floating point number to a C :ctype:`double`.
-
-``D`` (complex) [Py_complex]
- Convert a Python complex number to a C :ctype:`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 :ctype:`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 :ctype:`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
- :ctype:`void\*` argument that was passed to the :cfunc:`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 :ctype:`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 :ctype:`PyObject\*`.
-
-``t#`` (read-only character buffer) [char \*, int]
- Like ``s#``, but accepts any object which implements the read-only buffer
- interface. The :ctype:`char\*` variable is set to point to the first byte
- of the buffer, and the :ctype:`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 :ctype:`char \*` variable is set to point to the first byte
- of the buffer, and the :ctype:`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, :cfunc:`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 :cfunc:`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 :cfunc:`PyArg_Parse\*` functions
-return true, otherwise they return false and raise an appropriate exception.
-When the :cfunc:`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.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)
-
- Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list
- rather than a variable number of arguments.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)
-
- Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a
- va_list rather than a variable number of arguments.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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 :ctype:`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 :cfunc:`PyArg_UnpackTuple` in this example is entirely
- equivalent to this call to :cfunc:`PyArg_ParseTuple`::
-
- PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
-
- .. versionadded:: 2.2
-
- .. versionchanged:: 2.5
- This function used an :ctype:`int` type for *min* and *max*. This might
- require changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
-
- Create a new value based on a format string similar to those accepted by
- the :cfunc:`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.
-
- :cfunc:`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 :cfunc:`Py_BuildValue`. In other words, if your code invokes
- :cfunc:`malloc` and passes the allocated memory to :cfunc:`Py_BuildValue`,
- your code is responsible for calling :cfunc:`free` for that memory once
- :cfunc:`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 :ctype:`int` to a Python integer object.
-
- ``b`` (integer) [char]
- Convert a plain C :ctype:`char` to a Python integer object.
-
- ``h`` (integer) [short int]
- Convert a plain C :ctype:`short int` to a Python integer object.
-
- ``l`` (integer) [long int]
- Convert a C :ctype:`long int` to a Python integer object.
-
- ``B`` (integer) [unsigned char]
- Convert a C :ctype:`unsigned char` to a Python integer object.
-
- ``H`` (integer) [unsigned short int]
- Convert a C :ctype:`unsigned short int` to a Python integer object.
-
- ``I`` (integer/long) [unsigned int]
- Convert a C :ctype:`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 :ctype:`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 :ctype:`long long` to a Python long integer object. Only
- available on platforms that support :ctype:`long long`.
-
- ``K`` (long) [unsigned PY_LONG_LONG]
- Convert a C :ctype:`unsigned long long` to a Python long integer object.
- Only available on platforms that support :ctype:`unsigned long long`.
-
- ``n`` (int) [Py_ssize_t]
- Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer.
-
- .. versionadded:: 2.5
-
- ``c`` (string of length 1) [char]
- Convert a C :ctype:`int` representing a character to a Python string of
- length 1.
-
- ``d`` (float) [double]
- Convert a C :ctype:`double` to a Python floating point number.
-
- ``f`` (float) [float]
- Same as ``d``.
-
- ``D`` (complex) [Py_complex \*]
- Convert a C :ctype:`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, :cfunc:`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
- :ctype:`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.
-
-.. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)
-
- Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list
- rather than a variable number of arguments.
View
54 c-api/bool.rst
@@ -1,54 +0,0 @@
-.. 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.
-
-
-.. cfunction:: int PyBool_Check(PyObject *o)
-
- Return true if *o* is of type :cdata:`PyBool_Type`.
-
- .. versionadded:: 2.3
-
-
-.. cvar:: 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.
-
-
-.. cvar:: 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.
-
-
-.. cmacro:: Py_RETURN_FALSE
-
- Return :const:`Py_False` from a function, properly incrementing its reference
- count.
-
- .. versionadded:: 2.4
-
-
-.. cmacro:: Py_RETURN_TRUE
-
- Return :const:`Py_True` from a function, properly incrementing its reference
- count.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: 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
View
450 c-api/buffer.rst
@@ -1,450 +0,0 @@
-.. highlightlang:: c
-
-.. _bufferobjects:
-
-Buffers and Memoryview Objects
-------------------------------
-
-.. sectionauthor:: Greg Stein <gstein@lyra.org>
-.. 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
-:cfunc:`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.0 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
-==============================
-
-
-.. ctype:: Py_buffer
-
- .. cmember:: void *buf
-
- A pointer to the start of the memory for the object.
-
- .. cmember:: Py_ssize_t len
- :noindex:
-
- The total length of the memory in bytes.
-
- .. cmember:: int readonly
-
- An indicator of whether the buffer is read only.
-
- .. cmember:: 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.
-
- .. cmember:: int ndim
-
- The number of dimensions the memory represents as a multi-dimensional
- array. If it is 0, :cdata:`strides` and :cdata:`suboffsets` must be
- *NULL*.
-
- .. cmember:: Py_ssize_t *shape
-
- An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
- shape of the memory as a multi-dimensional array. Note that
- ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to
- :cdata:`len`.
-
- .. cmember:: Py_ssize_t *strides
-
- An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the
- number of bytes to skip to get to a new element in each dimension.
-
- .. cmember:: Py_ssize_t *suboffsets
-
- An array of :ctype:`Py_ssize_t`\s the length of :cdata:`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;
- }
-
-
- .. cmember:: 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 :cfunc:`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.
-
- .. cmember:: 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
-========================
-
-
-.. cfunction:: int PyObject_CheckBuffer(PyObject *obj)
-
- Return 1 if *obj* supports the buffer interface otherwise 0.
-
-
-.. cfunction:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)
-
- Export *obj* into a :ctype:`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
- :cdata:`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 |
- +==============================+===================================================+
- | :cmacro:`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. |
- | | |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is |
- | | not writable, then raise an error. |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_STRIDES` | This implies :cmacro:`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). |
- | | |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`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*. |
- | | |
- | | |
- | | |
- +------------------------------+---------------------------------------------------+
- |:cmacro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned |
- |:cmacro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last |
- |:cmacro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous |
- | | (first dimension varies the fastest) or either |
- | | one. All of these flags imply |
- | | :cmacro:`PyBUF_STRIDES` and guarantee that the |
- | | strides buffer info structure will be filled in |
- | | correctly. |
- | | |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`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 :cmacro:`PyBUF_STRIDES`. |
- | | |
- | | |
- | | |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`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) |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | |
- | | PyBUF_WRITABLE)``. |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. |
- | | |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | |
- | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | |
- | | PyBUF_FORMAT)``. |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |
- | | PyBUF_FORMAT | PyBUF_WRITABLE)``. |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |
- | | PyBUF_FORMAT)``. |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | |
- | | PyBUF_WRITABLE)``. |
- +------------------------------+---------------------------------------------------+
- | :cmacro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. |
- | | |
- +------------------------------+---------------------------------------------------+
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)
-
- Return the implied :cdata:`~Py_buffer.itemsize` from the struct-stype
- :cdata:`~Py_buffer.format`.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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.
-
-.. cfunction:: PyObject *PyMemoryView_FromObject(PyObject *obj)
-
- Create a memoryview object from an object that defines the new buffer
- interface.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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`.
-
-
-.. cfunction:: 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 :ctype:`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.
-
-
-.. ctype:: PyBufferObject
-
- This subtype of :ctype:`PyObject` represents a buffer object.
-
-
-.. cvar:: PyTypeObject PyBuffer_Type
-
- .. index:: single: BufferType (in module types)
-
- The instance of :ctype:`PyTypeObject` which represents the Python buffer type;
- it is the same object as ``buffer`` and ``types.BufferType`` in the Python
- layer. .
-
-
-.. cvar:: int Py_END_OF_BUFFER
-
- This constant may be passed as the *size* parameter to
- :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It
- indicates that the new :ctype:`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.
-
-
-.. cfunction:: int PyBuffer_Check(PyObject *p)
-
- Return true if the argument has type :cdata:`PyBuffer_Type`.
-
-
-.. cfunction:: 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 :ctype:`int` type for *offset* and *size*. This
- might require changes in your code for properly supporting 64-bit
- systems.
-
-
-.. cfunction:: 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 :cfunc:`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 :ctype:`int` type for *offset* and *size*. This
- might require changes in your code for properly supporting 64-bit
- systems.
-
-
-.. cfunction:: 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 :ctype:`int` type for *size*. This might require
- changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)
-
- Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is
- writable.
-
- .. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
- changes in your code for properly supporting 64-bit systems.
-
-
-.. cfunction:: 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
- :cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned.
-
- .. versionchanged:: 2.5
- This function used an :ctype:`int` type for *size*. This might require
- changes in your code for properly supporting 64-bit systems.
View
87 c-api/bytearray.rst
@@ -1,87 +0,0 @@
-.. highlightlang:: c
-
-.. _bytearrayobjects:
-
-Byte Array Objects
-------------------
-
-.. index:: object: bytearray
-
-.. versionadded:: 2.6
-
-
-.. ctype:: PyByteArrayObject
-
- This subtype of :ctype:`PyObject` represents a Python bytearray object.
-
-
-.. cvar:: PyTypeObject PyByteArray_Type
-
- This instance of :ctype:`PyTypeObject` represents the Python bytearray type;
- it is the same object as ``bytearray`` in the Python layer.
-
-Type check macros
-^^^^^^^^^^^^^^^^^
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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
-^^^^^^^^^^^^^^^^^^^^
-
-.. cfunction:: 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
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)
-
- Concat bytearrays *a* and *b* and return a new bytearray with the result.
-
-
-.. cfunction:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)
-
- Return the size of *bytearray* after checking for a *NULL* pointer.
-
-
-.. cfunction:: char* PyByteArray_AsString(PyObject *bytearray)
-
- Return the contents of *bytearray* as a char array after checking for a
- *NULL* pointer.
-
-
-.. cfunction:: 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.
-
-.. cfunction:: char* PyByteArray_AS_STRING(PyObject *bytearray)
-
- Macro version of :cfunc:`PyByteArray_AsString`.
-
-
-.. cfunction:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)
-
- Macro version of :cfunc:`PyByteArray_Size`.
View
150 c-api/capsule.rst
@@ -1,150 +0,0 @@
-.. highlightlang:: c
-
-.. _capsules:
-
-Capsules
---------
-
-.. index:: object: Capsule
-
-Refer to :ref:`using-capsules` for more information on using these objects.
-
-
-.. ctype:: PyCapsule
-
- This subtype of :ctype:`PyObject` represents an opaque value, useful for C
- extension modules who need to pass an opaque value (as a :ctype:`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.
-
-.. ctype:: PyCapsule_Destructor
-
- The type of a destructor callback for a capsule. Defined as::
-
- typedef void (*PyCapsule_Destructor)(PyObject *);
-
- See :cfunc:`PyCapsule_New` for the semantics of PyCapsule_Destructor
- callbacks.
-
-
-.. cfunction:: int PyCapsule_CheckExact(PyObject *p)
-
- Return true if its argument is a :ctype:`PyCapsule`.
-
-
-.. cfunction:: PyObject* PyCapsule_New(void *pointer, const char *name, PyCapsule_Destructor destructor)
-
- Create a :ctype:`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 :cfunc:`PyCapsule_Import`.
-
-
-.. cfunction:: 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 :cfunc:`strcmp` to compare capsule
- names.
-
-
-.. cfunction:: 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 :cfunc:`PyCapsule_IsValid` or
- :cfunc:`PyErr_Occurred` to disambiguate.
-
-
-.. cfunction:: 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 :cfunc:`PyCapsule_IsValid` or
- :cfunc:`PyErr_Occurred` to disambiguate.
-
-
-.. cfunction:: 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 :cfunc:`PyCapsule_IsValid` or
- :cfunc:`PyErr_Occurred` to disambiguate.
-
-
-.. cfunction:: 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 :cfunc:`PyImport_ImportModuleNoBlock`). If *no_block* is false,
- import the module conventionally (using :cfunc:`PyImport_ImportModule`).
-
- Return the capsule's internal *pointer* on success. On failure, set an
- exception and return *NULL*. However, if :cfunc:`PyCapsule_Import` failed to
- import the module, and *no_block* was true, no exception is set.
-
-.. cfunction:: int PyCapsule_IsValid(PyObject *capsule, const char *name)
-
- Determines whether or not *capsule* is a valid capsule. A valid capsule is
- non-*NULL*, passes :cfunc:`PyCapsule_CheckExact`, has a non-*NULL* pointer
- stored in it, and its internal name matches the *name* parameter. (See
- :cfunc:`PyCapsule_GetPointer` for information on how capsule names are
- compared.)
-
- In other words, if :cfunc:`PyCapsule_IsValid` returns a true value, calls to
- any of the accessors (any function starting with :cfunc:`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.
-
-.. cfunction:: 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.
-
-.. cfunction:: 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.
-
-.. cfunction:: 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.
-
-.. cfunction:: 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.
View
62 c-api/cell.rst
@@ -1,62 +0,0 @@
-.. 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.
-
-
-.. ctype:: PyCellObject
-
- The C structure used for cell objects.
-
-
-.. cvar:: PyTypeObject PyCell_Type
-
- The type object corresponding to cell objects.
-
-
-.. cfunction:: int PyCell_Check(ob)
-
- Return true if *ob* is a cell object; *ob* must not be *NULL*.
-
-
-.. cfunction:: PyObject* PyCell_New(PyObject *ob)
-
- Create and return a new cell object containing the value *ob*. The parameter may
- be *NULL*.
-
-
-.. cfunction:: PyObject* PyCell_Get(PyObject *cell)
-
- Return the contents of the cell *cell*.
-
-
-.. cfunction:: PyObject* PyCell_GET(PyObject *cell)
-
- Return the contents of the cell *cell*, but without checking that *cell* is
- non-*NULL* and a cell object.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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.
View
65 c-api/class.rst
@@ -1,65 +0,0 @@
-.. 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`).
-
-
-.. ctype:: PyClassObject
-
- The C structure of the objects used to describe built-in classes.
-
-
-.. cvar:: 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.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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.
-
-
-.. cvar:: PyTypeObject PyInstance_Type
-
- Type object for class instances.
-
-
-.. cfunction:: int PyInstance_Check(PyObject *obj)
-
- Return true if *obj* is an instance.
-
-
-.. cfunction:: 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.
-
-
-.. cfunction:: 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.
View
59 c-api/cobject.rst
@@ -1,59 +0,0 @@
-.. 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.
-
-.. ctype:: PyCObject
-
- This subtype of :ctype:`PyObject` represents an opaque value, useful for C
- extension modules who need to pass an opaque value (as a :ctype:`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.
-
-
-.. cfunction:: int PyCObject_Check(PyObject *p)
-
- Return true if its argument is a :ctype:`PyCObject`.
-
-
-.. cfunction:: PyObject* PyCObject_FromVoidPtr(void* cobj, void (*destr)(void *))
-
- Create a :ctype:`PyCObject` from the ``void *`` *cobj*. The *destr* function
- will be called when the object is reclaimed, unless it is *NULL*.
-
-
-.. cfunction:: PyObject* PyCObject_FromVoidPtrAndDesc(void* cobj, void* desc, void (*destr)(void *, void *))
-
- Create a :ctype:`PyCObject` from the :ctype:`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.
-
-
-.. cfunction:: void* PyCObject_AsVoidPtr(PyObject* self)
-
- Return the object :ctype:`void \*` that the :ctype:`PyCObject` *self* was
- created with.
-
-
-.. cfunction:: void* PyCObject_GetDesc(PyObject* self)
-
- Return the description :ctype:`void \*` that the :ctype:`PyCObject` *self* was
- created with.
-
-
-.. cfunction:: int PyCObject_SetVoidPtr(PyObject* self, void* cobj)
-
- Set the void pointer inside *self* to *cobj*. The :ctype:`PyCObject` must not
- have an associated destructor. Return true on success, false on failure.
View
50 c-api/code.rst
@@ -1,50 +0,0 @@
-.. highlightlang:: c
-
-.. _codeobjects:
-
-Code Objects
-------------
-
-.. sectionauthor:: Jeffrey Yasskin <jyasskin@gmail.com>
-
-
-.. 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.
-
-.. ctype:: PyCodeObject
-
- The C structure of the objects used to describe code objects. The
- fields of this type are subject to change at any time.
-
-
-.. cvar:: PyTypeObject PyCode_Type
-
- This is an instance of :ctype:`PyTypeObject` representing the Python
- :class:`code` type.
-
-
-.. cfunction:: int PyCode_Check(PyObject *co)
-
- Return true if *co* is a :class:`code` object
-
-.. cfunction:: int PyCode_GetNumFree(PyObject *co)
-
- Return the number of free variables in *co*.
-
-.. cfunction:: 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 :cfunc:`PyCode_NewEmpty` instead. Calling
- :cfunc:`PyCode_New` directly can bind you to a precise Python
- version since the definition of the bytecode changes often.
-
-
-.. cfunction:: 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.
View
118 c-api/codec.rst
@@ -1,118 +0,0 @@
-.. _codec-registry:
-
-Codec registry and support functions
-====================================
-
-.. cfunction:: 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.
-
-.. cfunction:: int PyCodec_KnownEncoding(const char *encoding)
-
- Return ``1`` or ``0`` depending on whether there is a registered codec for
- the given *encoding*.
-
-.. cfunction:: 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.
-
-.. cfunction:: 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.
-
-.. cfunction:: PyObject* PyCodec_Encoder(const char *encoding)
-
- Get an encoder function for the given *encoding*.
-
-.. cfunction:: PyObject* PyCodec_Decoder(const char *encoding)
-
- Get a decoder function for the given *encoding*.
-
-.. cfunction:: PyObject* PyCodec_IncrementalEncoder(const char *encoding, const char *errors)
-
- Get an :class:`IncrementalEncoder` object for the given *encoding*.
-
-.. cfunction:: PyObject* PyCodec_IncrementalDecoder(const char *encoding, const char *errors)
-
- Get an :class:`IncrementalDecoder` object for the given *encoding*.
-
-.. cfunction:: PyObject* PyCodec_StreamReader(const char *encoding, PyObject *stream, const char *errors)
-
- Get a :class:`StreamReader` factory function for the given *encoding*.
-
-.. cfunction:: 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
-------------------------------------------------
-
-.. cfunction:: 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.
-
-.. cfunction:: 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.
-
-.. cfunction:: PyObject* PyCodec_StrictErrors(PyObject *exc)
-
- Raise *exc* as an exception.
-
-.. cfunction:: PyObject* PyCodec_IgnoreErrors(PyObject *exc)
-
- Ignore the unicode error, skipping the faulty input.
-
-.. cfunction:: PyObject* PyCodec_ReplaceErrors(PyObject *exc)
-
- Replace the unicode encode error with ``?`` or ``U+FFFD``.
-
-.. cfunction:: PyObject* PyCodec_XMLCharRefReplaceErrors(PyObject *exc)
-
- Replace the unicode encode error with XML character references.
-
-.. cfunction:: PyObject* PyCodec_BackslashReplaceErrors(PyObject *exc)
-
- Replace the unicode encode error with backslash escapes (``\x``, ``\u`` and
- ``\U``).
-
View
132 c-api/complex.rst
@@ -1,132 +0,0 @@
-.. 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.
-
-
-.. ctype:: 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;
-
-
-.. cfunction:: Py_complex _Py_c_sum(Py_complex left, Py_complex right)
-
- Return the sum of two complex numbers, using the C :ctype:`Py_complex`
- representation.
-
-
-.. cfunction:: Py_complex _Py_c_diff(Py_complex left, Py_complex right)
-
- Return the difference between two complex numbers, using the C
- :ctype:`Py_complex` representation.
-
-
-.. cfunction:: Py_complex _Py_c_neg(Py_complex complex)
-
- Return the negation of the complex number *complex*, using the C
- :ctype:`Py_complex` representation.
-
-
-.. cfunction:: Py_complex _Py_c_prod(Py_complex left, Py_complex right)
-
- Return the product of two complex numbers, using the C :ctype:`Py_complex`
- representation.
-
-
-.. cfunction:: Py_complex _Py_c_quot(Py_complex dividend, Py_complex divisor)
-
- Return the quotient of two complex numbers, using the C :ctype:`Py_complex`
- representation.
-
-
-.. cfunction:: Py_complex _Py_c_pow(Py_complex num, Py_complex exp)
-
- Return the exponentiation of *num* by *exp*, using the C :ctype:`Py_complex`
- representation.
-
-
-Complex Numbers as Python Objects
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-
-.. ctype:: PyComplexObject
-
- This subtype of :ctype:`PyObject` represents a Python complex number object.
-
-
-.. cvar:: PyTypeObject PyComplex_Type
-
- This instance of :ctype:`PyTypeObject` represents the Python complex number
- type. It is the same object as ``complex`` and ``types.ComplexType``.
-
-
-.. cfunction:: int PyComplex_Check(PyObject *p)
-
- Return true if its argument is a :ctype:`PyComplexObject` or a subtype of
- :ctype:`PyComplexObject`.
-
- .. versionchanged:: 2.2
- Allowed subtypes to be accepted.
-
-
-.. cfunction:: int PyComplex_CheckExact(PyObject *p)
-
- Return true if its argument is a :ctype:`PyComplexObject`, but not a subtype of
- :ctype:`PyComplexObject`.
-
- .. versionadded:: 2.2
-
-
-.. cfunction:: PyObject* PyComplex_FromCComplex(Py_complex v)
-
- Create a new Python complex number object from a C :ctype:`Py_complex` value.
-
-
-.. cfunction:: PyObject* PyComplex_FromDoubles(double real, double imag)
-
- Return a new :ctype:`PyComplexObject` object from *real* and *imag*.
-
-
-.. cfunction:: double PyComplex_RealAsDouble(PyObject *op)
-
- Return the real part of *op* as a C :ctype:`double`.
-
-
-.. cfunction:: double PyComplex_ImagAsDouble(PyObject *op)
-
- Return the imaginary part of *op* as a C :ctype:`double`.
-
-
-.. cfunction:: Py_complex PyComplex_AsCComplex(PyObject *op)
-
- Return the :ctype:`Py_complex` value of the complex number *op*.
-
- .. 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.
View
109 c-api/concrete.rst
@@ -1,109 +0,0 @@
-.. 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 :cfunc:`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
View
181 c-api/conversion.rst
@@ -1,181 +0,0 @@
-.. highlightlang:: c
-
-.. _string-conversion:
-
-String conversion and formatting
-================================
-
-Functions for number conversion and formatted string output.
-
-
-.. cfunction:: 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)`.
-
-
-.. cfunction:: 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)`.
-
-:cfunc:`PyOS_snprintf` and :cfunc:`PyOS_vsnprintf` wrap the Standard C library
-functions :cfunc:`snprintf` and :cfunc:`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 :cfunc:`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.
-
-
-.. cfunction:: double PyOS_string_to_double(const char *s, char **endptr, PyObject *overflow_exception)
-
- Convert a string ``s`` to a :ctype:`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
-
-
-.. cfunction:: double PyOS_ascii_strtod(const char *nptr, char **endptr)
-
- Convert a string to a :ctype:`double`. This function behaves like the Standard C
- function :cfunc:`strtod` does in the C locale. It does this without changing the
- current locale, since that would not be thread-safe.
-
- :cfunc:`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 :cfunc:`PyOS_string_to_double` instead.
-
-
-
-.. cfunction:: char* PyOS_ascii_formatd(char *buffer, size_t buf_len, const char *format, double d)
-
- Convert a :ctype:`double` to a string using the ``'.'`` as the decimal
- separator. *format* is a :cfunc:`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.
-
-
-.. cfunction:: char* PyOS_double_to_string(double val, char format_code, int precision, int flags, int *ptype)
-
- Convert a :ctype:`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 :cfunc:`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 :cfunc:`PyMem_Free`.
-
- .. versionadded:: 2.7
-
-
-.. cfunction:: double PyOS_ascii_atof(const char *nptr)
-
- Convert a string to a :ctype:`double` in a locale-independent way.
-
- See the Unix man page :manpage:`atof(2)` for details.
-
- .. versionadded:: 2.4
-
- .. deprecated:: 3.1
- Use :cfunc:`PyOS_string_to_double` instead.
-
-
-.. cfunction:: char* PyOS_stricmp(char *s1, char *s2)
-
- Case insensitive comparison of strings. The function works almost
- identically to :cfunc:`strcmp` except that it ignores the case.
-
- .. versionadded:: 2.6
-
-
-.. cfunction:: char* PyOS_strnicmp(char *s1, char *s2, Py_ssize_t size)
-
- Case insensitive comparison of strings. The function works almost
- identically to :cfunc:`strncmp` except that it ignores the case.
-
- .. versionadded:: 2.6
View
239 c-api/datetime.rst
@@ -1,239 +0,0 @@
-.. 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 :cmacro:`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, :cdata:`PyDateTimeAPI`, that is used by the following
-macros.
-
-Type-check macros:
-
-
-.. cfunction:: int PyDate_Check(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of
- :cdata:`PyDateTime_DateType`. *ob* must not be *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDate_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DateType`. *ob* must not be
- *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_Check(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType` or a subtype of
- :cdata:`PyDateTime_DateTimeType`. *ob* must not be *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DateTimeType`. *ob* must not
- be *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyTime_Check(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_TimeType` or a subtype of
- :cdata:`PyDateTime_TimeType`. *ob* must not be *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyTime_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_TimeType`. *ob* must not be
- *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDelta_Check(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DeltaType` or a subtype of
- :cdata:`PyDateTime_DeltaType`. *ob* must not be *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDelta_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_DeltaType`. *ob* must not be
- *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyTZInfo_Check(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType` or a subtype of
- :cdata:`PyDateTime_TZInfoType`. *ob* must not be *NULL*.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyTZInfo_CheckExact(PyObject *ob)
-
- Return true if *ob* is of type :cdata:`PyDateTime_TZInfoType`. *ob* must not be
- *NULL*.
-
- .. versionadded:: 2.4
-
-Macros to create objects:
-
-
-.. cfunction:: PyObject* PyDate_FromDate(int year, int month, int day)
-
- Return a ``datetime.date`` object with the specified year, month and day.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: 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
-
-
-.. cfunction:: 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
-
-
-.. cfunction:: 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
-:cdata:`PyDateTime_Date`, including subclasses (such as
-:cdata:`PyDateTime_DateTime`). The argument must not be *NULL*, and the type is
-not checked:
-
-
-.. cfunction:: int PyDateTime_GET_YEAR(PyDateTime_Date *o)
-
- Return the year, as a positive int.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_GET_MONTH(PyDateTime_Date *o)
-
- Return the month, as an int from 1 through 12.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: 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 :cdata:`PyDateTime_DateTime`, including subclasses. The argument
-must not be *NULL*, and the type is not checked:
-
-
-.. cfunction:: int PyDateTime_DATE_GET_HOUR(PyDateTime_DateTime *o)
-
- Return the hour, as an int from 0 through 23.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_DATE_GET_MINUTE(PyDateTime_DateTime *o)
-
- Return the minute, as an int from 0 through 59.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_DATE_GET_SECOND(PyDateTime_DateTime *o)
-
- Return the second, as an int from 0 through 59.
-
- .. versionadded:: 2.4
-
-
-.. cfunction:: int PyDateTime_DATE_GET_MICROSECOND(PyDateTime_DateTime *o)