Skip to content

C
cpython
Commit 0051bf31 authored by Jeroen Ruigrok van der Werven's avatar Jeroen Ruigrok van der Werven
Browse files
Options

Merged revisions... 

Merged revisions 71873-71874,71882,71890,71893,71898-71900,71910,71914-71923,71925-71929,71931-71934,71937 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/trunk

........
  r71873 | jeroen.ruigrok | 2009-04-25 13:15:06 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to expanding.
........
  r71874 | jeroen.ruigrok | 2009-04-25 13:59:09 +0200 (za, 25 apr 2009) | 2 lines

  First attempt to document PyObject_HEAD_INIT and PyVarObject_HEAD_INIT.
........
  r71882 | jeroen.ruigrok | 2009-04-25 14:49:10 +0200 (za, 25 apr 2009) | 3 lines

  Issue #4239: adjust email examples not to use connect() and terminate with
  quit() and not close().
........
  r71890 | jeroen.ruigrok | 2009-04-25 15:07:40 +0200 (za, 25 apr 2009) | 3 lines

  Rewrite a sentence to be more in line with the rest of the documentation with
  regard to person and audience.
........
  r71893 | jeroen.ruigrok | 2009-04-25 15:58:58 +0200 (za, 25 apr 2009) | 2 lines

  Reformat file prior to editing.
........
  r71898 | jeroen.ruigrok | 2009-04-25 16:24:30 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71899 | jeroen.ruigrok | 2009-04-25 16:27:00 +0200 (za, 25 apr 2009) | 3 lines

  The type for ppos has been Py_ssize_t since 2.5, reflect this in the
  documentation.
........
  r71900 | jeroen.ruigrok | 2009-04-25 16:28:02 +0200 (za, 25 apr 2009) | 2 lines

  Reformat paragraph.
........
  r71910 | jeroen.ruigrok | 2009-04-25 19:59:03 +0200 (za, 25 apr 2009) | 4 lines

  Issue #4129: Belatedly document which C API functions had their argument(s) or
  return type changed from int or int * to Py_ssize_t or Py_ssize_t * as this
  might cause problems on 64-bit platforms.
........
  r71914 | jeroen.ruigrok | 2009-04-25 20:31:20 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71915 | jeroen.ruigrok | 2009-04-25 20:46:03 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: Document more int -> Py_ssize_t changes.
........
  r71916 | jeroen.ruigrok | 2009-04-25 20:53:48 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71917 | jeroen.ruigrok | 2009-04-25 20:57:32 +0200 (za, 25 apr 2009) | 2 lines

  Reference to an int type, whereas it's a Py_ssize_t as the synopsis states.
........
  r71918 | jeroen.ruigrok | 2009-04-25 21:04:15 +0200 (za, 25 apr 2009) | 2 lines

  Since I edited this file, reformat for future edits.
........
  r71919 | jeroen.ruigrok | 2009-04-25 21:10:52 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71920 | jeroen.ruigrok | 2009-04-25 21:44:55 +0200 (za, 25 apr 2009) | 5 lines

  Issue #4129: More documentation pointers about int -> Py_ssize_t.
  Also fix up the documentation for PyObject_GC_Resize(). It seems that since
  it first got documented, the documentation was actually for
  _PyObject_GC_Resize().
........
  r71921 | jeroen.ruigrok | 2009-04-25 21:46:19 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: Documentation notes for int -> Py_ssize_t changes.
........
  r71922 | jeroen.ruigrok | 2009-04-25 21:49:05 +0200 (za, 25 apr 2009) | 2 lines

  Reformat, since I've been busy here anyway.
........
  r71923 | jeroen.ruigrok | 2009-04-25 21:54:34 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: Add a versionchanged notice for a few forgotten entries.
........
  r71925 | jeroen.ruigrok | 2009-04-25 22:37:39 +0200 (za, 25 apr 2009) | 2 lines

  Since it's a macro, actually refer to it as such instead of function.
........
  r71926 | jeroen.ruigrok | 2009-04-25 22:40:10 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71927 | jeroen.ruigrok | 2009-04-25 22:41:40 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: int -> Py_ssize_t documentation.
........
  r71928 | jeroen.ruigrok | 2009-04-25 22:43:30 +0200 (za, 25 apr 2009) | 2 lines

  Reformat prior to editing.
........
  r71929 | jeroen.ruigrok | 2009-04-25 22:44:58 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: int -> Py_ssize_t documentation.
........
  r71931 | jeroen.ruigrok | 2009-04-25 22:50:27 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: int -> Py_ssize_t documentation.
........
  r71932 | jeroen.ruigrok | 2009-04-25 22:55:39 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: more int -> Py_ssize_t documentation.
........
  r71933 | jeroen.ruigrok | 2009-04-25 22:58:35 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: more int -> Py_ssize_t documentation.
........
  r71934 | jeroen.ruigrok | 2009-04-25 23:02:34 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: field changed from int to Py_ssize_t.
........
  r71937 | jeroen.ruigrok | 2009-04-25 23:16:05 +0200 (za, 25 apr 2009) | 2 lines

  Issue #4129: document int -> Py_ssize_t changes.
........
parent 01e117ff
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 1310 additions and 576 deletions
Doc/c-api/allocation.rst
View file @ 0051bf31
......@@ -11,16 +11,21 @@ Allocating Objects on the Heap
.. 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.
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)
......@@ -28,77 +33,90 @@ Allocating Objects on the Heap
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.
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.
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.
: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.
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.
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.
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.
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`.
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.
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.
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.
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.
Doc/c-api/arg.rst
View file @ 0051bf31
This diff is collapsed.
Doc/c-api/buffer.rst
View file @ 0051bf31
This diff is collapsed.
Doc/c-api/dict.rst
View file @ 0051bf31
......@@ -19,8 +19,9 @@ Dictionary Objects
single: DictType (in module types)
single: DictionaryType (in module types)
This instance of :ctype:`PyTypeObject` represents the Python dictionary type.
This is exposed to Python programs as ``dict`` and ``types.DictType``.
This instance of :ctype:`PyTypeObject` represents the Python dictionary
type. This is exposed to Python programs as ``dict`` and
``types.DictType``.
.. cfunction:: int PyDict_Check(PyObject *p)
......@@ -34,8 +35,8 @@ Dictionary Objects
.. cfunction:: int PyDict_CheckExact(PyObject *p)
Return true if *p* is a dict object, but not an instance of a subtype of the
dict type.
Return true if *p* is a dict object, but not an instance of a subtype of
the dict type.
.. versionadded:: 2.4
......@@ -47,9 +48,9 @@ Dictionary Objects
.. cfunction:: 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.
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
......@@ -61,9 +62,9 @@ Dictionary Objects
.. cfunction:: 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``.
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
......@@ -78,24 +79,25 @@ Dictionary Objects
.. cfunction:: 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.
:term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return
``0`` on success or ``-1`` on failure.
.. cfunction:: 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
:ctype:`char\*`. The key object is created using ``PyString_FromString(key)``.
Return ``0`` on success or ``-1`` on failure.
Insert *value* into the dictionary *p* using *key* as a key. *key* should
be a :ctype:`char\*`. The key object is created using
``PyString_FromString(key)``. Return ``0`` on success or ``-1`` on
failure.
.. cfunction:: 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.
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.
.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)
......@@ -106,8 +108,8 @@ Dictionary Objects
.. cfunction:: 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.
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.
.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)
......@@ -118,41 +120,46 @@ Dictionary Objects
.. cfunction:: PyObject* PyDict_Items(PyObject *p)
Return a :ctype:`PyListObject` containing all the items from the dictionary, as
in the dictionary method :meth:`dict.items`.
Return a :ctype:`PyListObject` containing all the items from the
dictionary, as in the dictionary method :meth:`dict.items`.
.. cfunction:: PyObject* PyDict_Keys(PyObject *p)
Return a :ctype:`PyListObject` containing all the keys from the dictionary, as
in the dictionary method :meth:`dict.keys`.
Return a :ctype:`PyListObject` containing all the keys from the dictionary,
as in the dictionary method :meth:`dict.keys`.
.. cfunction:: PyObject* PyDict_Values(PyObject *p)
Return a :ctype:`PyListObject` containing all the values from the dictionary
*p*, as in the dictionary method :meth:`dict.values`.
Return a :ctype:`PyListObject` containing all the values from the
dictionary *p*, as in the dictionary method :meth:`dict.values`.
.. cfunction:: 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.
Return the number of items in the dictionary. This is equivalent to
``len(p)`` on a dictionary.
.. versionchanged:: 2.5
This function returned an :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)
Iterate over all key-value pairs in the dictionary *p*. The :ctype:`int`
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 :ctype:`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.
Iterate over all key-value pairs in the dictionary *p*. The
:ctype:`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 :ctype:`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::
......@@ -164,9 +171,10 @@ Dictionary Objects
...
}
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::
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;
......@@ -183,15 +191,19 @@ Dictionary Objects
Py_DECREF(o);
}
.. versionchanged:: 2.5
This function used an :ctype:`int *` type for *ppos*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :func:`PyMapping_Keys` and
: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.
Iterate over mapping object *b* adding key-value pairs to dictionary *a*.
*b* may be a dictionary, or any object supporting :func:`PyMapping_Keys`
and :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
......@@ -206,11 +218,12 @@ Dictionary Objects
.. cfunction:: 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)::
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:
......
Doc/c-api/gcsupport.rst
View file @ 0051bf31
......@@ -9,7 +9,8 @@ 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.
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)".
......@@ -23,13 +24,14 @@ include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the
.. 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.
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 :cfunc:`PyObject_GC_New` or
:cfunc:`PyObject_GC_VarNew`.
#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New`
or :cfunc:`PyObject_GC_VarNew`.
#. Once all the fields which may contain references to other containers are
initialized, it must call :cfunc:`PyObject_GC_Track`.
......@@ -46,20 +48,28 @@ Constructors for container types must conform to two rules:
Analogous to :cfunc:`PyObject_NewVar` but for container objects with the
:const:`Py_TPFLAGS_HAVE_GC` flag set.
.. 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:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)
Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the resized
object or *NULL* on failure.
.. cfunction:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the
resized object or *NULL* on failure.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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.
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.
.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)
......@@ -85,10 +95,10 @@ rules:
.. cfunction:: void PyObject_GC_UnTrack(void *op)
Remove the object *op* from the set of container objects tracked by the
collector. Note that :cfunc:`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.
collector. Note that :cfunc:`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.
.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)
......@@ -101,11 +111,12 @@ The :attr:`tp_traverse` handler accepts a function parameter of this type:
.. ctype:: 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.
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:
......@@ -114,10 +125,10 @@ The :attr:`tp_traverse` handler must have the following type:
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.
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 :cfunc:`Py_VISIT` macro is
provided. In order to use this macro, the :attr:`tp_traverse` implementation
......@@ -126,9 +137,9 @@ must name its arguments exactly *visit* and *arg*:
.. cfunction:: 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::
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)
......@@ -140,14 +151,15 @@ must name its arguments exactly *visit* and *arg*:
.. versionadded:: 2.4
The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL* if
the object is immutable.
The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL*
if the object is immutable.
.. ctype:: 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 :cfunc:`Py_DECREF` on a reference). The collector will call
this method if it detects that this object is involved in a reference cycle.
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 :cfunc:`Py_DECREF` on a reference). The
collector will call this method if it detects that this object is involved
in a reference cycle.
Doc/c-api/init.rst
View file @ 0051bf31
......@@ -491,13 +491,13 @@ 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.
Why am I going on with so much detail about this? Because when threads are
created from C, they don't have the global interpreter lock, nor is there a
thread state data structure for them. Such threads must bootstrap themselves
into existence, by first creating a thread state data structure, then acquiring
the lock, and finally storing their thread state pointer, before they can start
using the Python/C API. When they are done, they should reset the thread state
pointer, release the lock, and finally free their thread state data structure.
It is important to note that when threads are created from C, they don't have
the global interpreter lock, nor is there a thread state data structure for
them. Such threads must bootstrap themselves into existence, by first
creating a thread state data structure, then acquiring the lock, and finally
storing their thread state pointer, before they can start using the Python/C
API. When they are done, they should reset the thread state pointer, release
the lock, and finally free their thread state data structure.
Beginning with version 2.3, threads can now take advantage of the
:cfunc:`PyGILState_\*` functions to do all of the above automatically. The
......
Doc/c-api/list.rst
View file @ 0051bf31
......@@ -17,8 +17,9 @@ List Objects
.. index:: single: ListType (in module types)
This instance of :ctype:`PyTypeObject` represents the Python list type. This is
the same object as ``list`` and ``types.ListType`` in the Python layer.
This instance of :ctype:`PyTypeObject` represents the Python list type.
This is the same object as ``list`` and ``types.ListType`` in the Python
layer.
.. cfunction:: int PyList_Check(PyObject *p)
......@@ -32,8 +33,8 @@ List Objects
.. cfunction:: int PyList_CheckExact(PyObject *p)
Return true if *p* is a list object, but not an instance of a subtype of the
list type.
Return true if *p* is a list object, but not an instance of a subtype of
the list type.
.. versionadded:: 2.2
......@@ -44,10 +45,14 @@ List Objects
.. note::
If *length* is greater than zero, the returned list object's items are set to
``NULL``. Thus you cannot use abstract API functions such as
:cfunc:`PySequence_SetItem` or expose the object to Python code before setting
all items to a real object with :cfunc:`PyList_SetItem`.
If *length* is greater than zero, the returned list object's items are
set to ``NULL``. Thus you cannot use abstract API functions such as
:cfunc:`PySequence_SetItem` or expose the object to Python code before
setting all items to a real object with :cfunc:`PyList_SetItem`.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)
......@@ -57,80 +62,118 @@ List Objects
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 :ctype:`int`. This might require changes in
your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)
Macro form of :cfunc:`PyList_Size` without error checking.
.. versionchanged:: 2.5
This macro returned an :ctype:`int`. This might require changes in your
code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
Return the object at position *pos* in the list pointed to by *p*. The position
must be positive, indexing from the end of the list is not supported. If *pos*
is out of bounds, return *NULL* and set an :exc:`IndexError` exception.
Return the object at position *pos* in the list pointed to by *p*. The
position must be positive, indexing from the end of the list is not
supported. If *pos* is out of bounds, return *NULL* and set an
:exc:`IndexError` exception.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)
Macro form of :cfunc:`PyList_GetItem` without error checking.
.. versionchanged:: 2.5
This macro used an :ctype:`int` for *i*. This might require changes in
your code for properly supporting 64-bit systems.
.. cfunction:: 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.
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.
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 :ctype:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally
only used to fill in new lists where there is no previous content.
Macro form of :cfunc:`PyList_SetItem` without error checking. This is
normally only used to fill in new lists where there is no previous content.
.. note::
This function "steals" a reference to *item*, and, unlike
:cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it
being replaced; any reference in *list* at position *i* will be leaked.
This macro "steals" a reference to *item*, and, unlike
:cfunc:`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 :ctype:`int` for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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)``.
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 :ctype:`int` for *index*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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)``.
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)``.
.. cfunction:: 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]``.
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]``.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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.
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.
.. versionchanged:: 2.5
This function used an :ctype:`int` for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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()``.
Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
failure. This is equivalent to ``list.sort()``.
.. cfunction:: int PyList_Reverse(PyObject *list)
......
Doc/c-api/long.rst
View file @ 0051bf31
......@@ -106,6 +106,10 @@ Long Integer Objects
.. versionadded:: 1.6
.. versionchanged:: 2.5
This function used an :ctype:`int` for *length*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)
......
Doc/c-api/mapping.rst
View file @ 0051bf31
......@@ -12,7 +12,8 @@ Mapping Protocol
function always succeeds.
.. cfunction:: Py_ssize_t PyMapping_Length(PyObject *o)
.. cfunction:: Py_ssize_t PyMapping_Size(PyObject *o)
Py_ssize_t PyMapping_Length(PyObject *o)
.. index:: builtin: len
......@@ -20,6 +21,10 @@ Mapping Protocol
objects that do not provide mapping protocol, this is equivalent to the Python
expression ``len(o)``.
.. versionchanged:: 2.5
These functions returned an :ctype:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key)
......
Doc/c-api/marshal.rst
View file @ 0051bf31
......@@ -5,25 +5,26 @@
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.
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).
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).
.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
Marshal a :ctype:`long` integer, *value*, to *file*. This will only write the
least-significant 32 bits of *value*; regardless of the size of the native
:ctype:`long` type.
Marshal a :ctype:`long` integer, *value*, to *file*. This will only write
the least-significant 32 bits of *value*; regardless of the size of the
native :ctype:`long` type.
.. versionchanged:: 2.4
*version* indicates the file format.
......@@ -48,24 +49,24 @@ floating point numbers.
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?
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?
.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
reading. Only a 32-bit value can be read in using this function, regardless of
the native size of :ctype:`long`.
Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened
for reading. Only a 32-bit value can be read in using this function,
regardless of the native size of :ctype:`long`.
.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
reading. Only a 16-bit value can be read in using this function, regardless of
the native size of :ctype:`short`.
Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened
for reading. Only a 16-bit value can be read in using this function,
regardless of the native size of :ctype:`short`.
.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
......@@ -78,17 +79,22 @@ using these routines?
.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
Return a Python object from the data stream in a :ctype:`FILE\*` opened for
reading. Unlike :cfunc:`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*.
reading. Unlike :cfunc:`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*.
.. cfunction:: 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*.
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 :ctype:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.
Doc/c-api/objbuffer.rst
View file @ 0051bf31
......@@ -2,30 +2,46 @@
.. _abstract-buffer:
Buffer Protocol
===============
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.0 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.
.. cfunction:: 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.
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 :ctype:`int *` type for *buffer_len*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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.
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 :ctype:`int *` type for *buffer_len*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
......@@ -38,9 +54,13 @@ Buffer Protocol
.. cfunction:: 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.
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 :ctype:`int *` type for *buffer_len*. This might
require changes in your code for properly supporting 64-bit systems.
Doc/c-api/object.rst
View file @ 0051bf31
......@@ -351,6 +351,10 @@ is considered sufficient for this determination.
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 :ctype:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)
......
Doc/c-api/sequence.rst
View file @ 0051bf31
......@@ -13,6 +13,7 @@ Sequence Protocol
.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)
Py_ssize_t PySequence_Length(PyObject *o)
.. index:: builtin: len
......@@ -20,10 +21,9 @@ Sequence Protocol
For objects that do not provide sequence protocol, this is equivalent to the
Python expression ``len(o)``.
.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o)
Alternate name for :cfunc:`PySequence_Size`.
.. versionchanged:: 2.5
These functions returned an :ctype:`int` type. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)
......@@ -37,6 +37,10 @@ Sequence Protocol
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 :ctype:`int` type for *count*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)
......@@ -51,18 +55,30 @@ Sequence Protocol
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 :ctype:`int` type for *count*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :ctype:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :ctype:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)
......@@ -70,24 +86,40 @@ Sequence Protocol
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 :ctype:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :ctype:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :ctype:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :ctype:`int` type for *i1* and *i2*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)
......@@ -95,6 +127,10 @@ Sequence Protocol
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 :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)
......@@ -108,6 +144,10 @@ Sequence Protocol
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 :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PySequence_List(PyObject *o)
......@@ -138,6 +178,10 @@ Sequence Protocol
Return the *i*th element of *o*, assuming that *o* was returned by
:cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
......@@ -160,6 +204,10 @@ Sequence Protocol
.. versionadded:: 2.3
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *i*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
......
Doc/c-api/set.rst
View file @ 0051bf31
......@@ -116,6 +116,10 @@ or :class:`frozenset` or instances of their subtypes.
``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 :ctype:`int`. This might require changes in
your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)
......
Doc/c-api/slice.rst
View file @ 0051bf31
......@@ -22,35 +22,47 @@ Slice Objects
.. cfunction:: 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.
*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.
.. cfunction:: 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.
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).
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 :cfunc:`PySlice_GetIndicesEx`, suitably renamed, in the source of
your extension.
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 :cfunc:`PySlice_GetIndicesEx`, suitably renamed,
in the source of your extension.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *length* and an
:ctype:`int *` type for *start*, *stop*, and *step*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :cfunc:`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.
Usable replacement for :cfunc:`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 :ctype:`int` type for *length* and an
:ctype:`int *` type for *start*, *stop*, *step*, and *slicelength*. This
might require changes in your code for properly supporting 64-bit
systems.
Doc/c-api/string.rst
View file @ 0051bf31
......@@ -58,6 +58,10 @@ called with a non-string parameter.
*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 :ctype:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)
......@@ -132,11 +136,19 @@ called with a non-string parameter.
Return the length of the string in string object *string*.
.. versionchanged:: 2.5
This function returned an :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)
Macro form of :cfunc:`PyString_Size` but without error checking.
.. versionchanged:: 2.5
This macro returned an :ctype:`int` type. This might require changes in
your code for properly supporting 64-bit systems.
.. cfunction:: char* PyString_AsString(PyObject *string)
......@@ -172,6 +184,10 @@ called with a non-string parameter.
*string* and operates on that. If *string* is not a string object at all,
:cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.
.. versionchanged:: 2.5
This function used an :ctype:`int *` type for *length*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)
......@@ -200,6 +216,9 @@ called with a non-string parameter.
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 :ctype:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)
......@@ -236,6 +255,10 @@ called with a non-string parameter.
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 :ctype:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)
......@@ -254,6 +277,10 @@ called with a non-string parameter.
: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 :ctype:`int` type for *size*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)
......
Doc/c-api/structures.rst
View file @ 0051bf31
This diff is collapsed.
Doc/c-api/tuple.rst
View file @ 0051bf31
......@@ -42,6 +42,10 @@ Tuple Objects
Return a new tuple object of size *len*, or *NULL* on failure.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *len*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyTuple_Pack(Py_ssize_t n, ...)
......@@ -51,34 +55,58 @@ Tuple Objects
.. versionadded:: 2.4
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *n*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :ctype:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyTuple_GET_ITEM(PyObject *p, Py_ssize_t pos)
Like :cfunc:`PyTuple_GetItem`, but does no checking of its arguments.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: 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 :ctype:`int` type for *low* and *high*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyTuple_SetItem(PyObject *p, Py_ssize_t pos, PyObject *o)
......@@ -89,6 +117,10 @@ Tuple Objects
This function "steals" a reference to *o*.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: void PyTuple_SET_ITEM(PyObject *p, Py_ssize_t pos, PyObject *o)
......@@ -99,6 +131,10 @@ Tuple Objects
This function "steals" a reference to *o*.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *pos*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: int _PyTuple_Resize(PyObject **p, Py_ssize_t newsize)
......@@ -116,6 +152,10 @@ Tuple Objects
.. versionchanged:: 2.2
Removed unused third parameter, *last_is_sticky*.
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *newsize*. This might
require changes in your code for properly supporting 64-bit systems.
.. cfunction:: int PyTuple_ClearFreeList(void)
......
Doc/c-api/type.rst
View file @ 0051bf31
......@@ -76,6 +76,10 @@ Type Objects
.. versionadded:: 2.2
.. versionchanged:: 2.5
This function used an :ctype:`int` type for *nitems*. This might require
changes in your code for properly supporting 64-bit systems.
.. cfunction:: PyObject* PyType_GenericNew(PyTypeObject *type, PyObject *args, PyObject *kwds)
......
Doc/c-api/typeobj.rst
View file @ 0051bf31
......@@ -64,6 +64,10 @@ type objects) *must* have the :attr:`ob_size` field.
This field is not inherited by subtypes.
.. versionchanged:: 2.5
This field used to be an :ctype:`int` type. This might require changes
in your code for properly supporting 64-bit systems.
.. cmember:: PyTypeObject* PyObject.ob_type
......
Doc/c-api/unicode.rst
View file @ 0051bf31
This diff is collapsed.
Doc/includes/email-alternative.py
View file @ 0051bf31
......@@ -45,4 +45,4 @@ s = smtplib.SMTP('localhost')
# sendmail function takes 3 arguments: sender's address, recipient's address
# and message to send - here it is sent as one string.
s.sendmail(me, you, msg.as_string())
s.close()
s.quit()
Doc/includes/email-dir.py
View file @ 0051bf31
......@@ -106,9 +106,8 @@ must be running an SMTP server.
fp.close()
else:
s = smtplib.SMTP()
s.connect()
s.sendmail(opts.sender, opts.recipients, composed)
s.close()
s.quit()
if __name__ == '__main__':
......
Doc/includes/email-mime.py
View file @ 0051bf31
......@@ -27,6 +27,5 @@ for file in pngfiles:
# Send the email via our own SMTP server.
s = smtplib.SMTP()
s.connect()
s.sendmail(me, family, msg.as_string())
s.close()
s.quit()
Doc/includes/email-simple.py
View file @ 0051bf31
......@@ -20,6 +20,5 @@ msg['To'] = you
# Send the message via our own SMTP server, but don't include the
# envelope header.
s = smtplib.SMTP()
s.connect()
s.sendmail(me, [you], msg.as_string())
s.close()
s.quit()
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7