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.
........
diff --git a/Doc/c-api/allocation.rst b/Doc/c-api/allocation.rst
index 75be457..28b9c56 100644
--- a/Doc/c-api/allocation.rst
+++ b/Doc/c-api/allocation.rst
@@ -11,16 +11,21 @@
.. 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 @@
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.