Skip to content

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

Merged revisions 71920-71923,71925-71929,71931-71934,71937 via svnmerge from 

svn+ssh://pythondev@svn.python.org/python/trunk

........
  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 9ec39672
Expand all Hide whitespace changes
Inline Side-by-side
Showing with 283 additions and 76 deletions
Doc/c-api/allocation.rst
View file @ 158777ae
......@@ -30,6 +30,10 @@ 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)
......@@ -51,6 +55,10 @@ Allocating Objects on the Heap
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)
......
Doc/c-api/gcsupport.rst
View file @ 158777ae
......@@ -45,12 +45,20 @@ 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)
.. 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)
......
Doc/c-api/list.rst
View file @ 158777ae
......@@ -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)
......@@ -29,8 +30,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.
.. cfunction:: PyObject* PyList_New(Py_ssize_t len)
......@@ -39,10 +40,10 @@ 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
......@@ -65,12 +66,17 @@ List Objects
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
......@@ -81,16 +87,20 @@ List Objects
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
......@@ -99,21 +109,26 @@ List Objects
.. 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
is 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
......@@ -122,16 +137,16 @@ List Objects
.. 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
......@@ -140,10 +155,10 @@ List Objects
.. 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
......@@ -152,8 +167,8 @@ List Objects
.. 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/marshal.rst
View file @ 158777ae
......@@ -5,24 +5,25 @@
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 shares interned strings in the file, and upon unmarshalling.
Version 2 uses a binary format for floating point numbers.
The module supports two versions of the data format: version 0 is the
historical version, version 1 shares interned strings in the file, and upon
unmarshalling. Version 2 uses a binary format for floating point numbers.
*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
.. 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. *version* indicates the file format.
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. *version* indicates the file format.
.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
......@@ -40,24 +41,24 @@ Version 2 uses a binary format for 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)
......@@ -70,17 +71,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 @ 158777ae
......@@ -10,17 +10,26 @@ Buffer Protocol
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.
.. 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.
.. 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)
......@@ -32,6 +41,11 @@ Buffer Protocol
.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
Returns a pointer to a writable memory location. The *obj* argument must
support the single-segment, character buffer interface. On success, returns
``0``, sets *buffer* to the memory location and *buffer_len* to the buffer
length. Returns ``-1`` and sets a :exc:`TypeError` on error.
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.
.. 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/sequence.rst
View file @ 158777ae
......@@ -178,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)
......@@ -196,6 +200,10 @@ Sequence Protocol
:cfunc:`PySequence_Check(o)` is true and without adjustment for negative
indices.
.. 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/tuple.rst
View file @ 158777ae
......@@ -67,6 +67,10 @@ Tuple Objects
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)
......@@ -82,6 +86,10 @@ Tuple Objects
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)
......@@ -116,6 +124,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)
......
Doc/c-api/typeobj.rst
View file @ 158777ae
......@@ -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 @ 158777ae
This diff is collapsed.
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