FFFF Merged revisions 71920-71923,71925-71929,71931-71934,71937 via svnmer… · python/cpython@47a7d70 · GitHub
[go: up one dir, main page]
Skip to content

Commit 47a7d70

Browse files
ashemedaiashemedai
committed
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. ........
1 parent 5c32f67 commit 47a7d70

File tree

Collapse file tree

9 files changed

+283
-76
lines changed

9 files changed

+283
-76
lines changed

‎Doc/c-api/allocation.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -30,6 +30,10 @@ Allocating Objects on the Heap
3030
This does everything :cfunc:`PyObject_Init` does, and also initializes the
3131
length information for a variable-size object.
3232

33+
.. versionchanged:: 2.5
34+
This function used an :ctype:`int` type for *size*. This might require
35+
changes in your code for properly supporting 64-bit systems.
36+
3337

3438
.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
3539

@@ -51,6 +55,10 @@ Allocating Objects on the Heap
5155
fields into the same allocation decreases the number of allocations,
5256
improving the memory management efficiency.
5357

58+
.. versionchanged:: 2.5
59+
This function used an :ctype:`int` type for *size*. This might require
60+
changes in your code for properly supporting 64-bit systems.
61+
5462

5563
.. cfunction:: void PyObject_Del(PyObject *op)
5664

‎Doc/c-api/gcsupport.rst‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -45,12 +45,20 @@ Constructors for container types must conform to two rules:
4545
Analogous to :cfunc:`PyObject_NewVar` but for container objects with the
4646
:const:`Py_TPFLAGS_HAVE_GC` flag set.
4747

48+
.. versionchanged:: 2.5
49+
This function used an :ctype:`int` type for *size*. This might require
50+
changes in your code for properly supporting 64-bit systems.
4851

49-
.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)
52+
53+
.. cfunction:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)
5054

5155
Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the
5256
resized object or *NULL* on failure.
5357

58+
.. versionchanged:: 2.5
59+
This function used an :ctype:`int` type for *newsize*. This might
60+
require changes in your code for properly supporting 64-bit systems.
61+
5462

5563
.. cfunction:: void PyObject_GC_Track(PyObject *op)
5664

‎Doc/c-api/list.rst‎

Lines changed: 50 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,9 @@ List Objects
1717

1818
.. index:: single: ListType (in module types)
1919

20-
This instance of :ctype:`PyTypeObject` represents the Python list type. This is
21-
the same object as ``list`` and ``types.ListType`` in the Python layer.
20+
This instance of :ctype:`PyTypeObject` represents the Python list type.
21+
This is the same object as ``list`` and ``types.ListType`` in the Python
22+
layer.
2223

2324

2425
.. cfunction:: int PyList_Check(PyObject *p)
@@ -29,8 +30,8 @@ List Objects
2930

3031
.. cfunction:: int PyList_CheckExact(PyObject *p)
3132

32-
Return true if *p* is a list object, but not an instance of a subtype of the
33-
list type.
33+
Return true if *p* is a list object, but not an instance of a subtype of
34+
the list type.
3435

3536

3637
.. cfunction:: PyObject* PyList_New(Py_ssize_t len)
@@ -39,10 +40,10 @@ List Objects
3940

4041
.. note::
4142

42-
If *length* is greater than zero, the returned list object's items are set to
43-
``NULL``. Thus you cannot use abstract API functions such as
44-
:cfunc:`PySequence_SetItem` or expose the object to Python code before setting
45-
all items to a real object with :cfunc:`PyList_SetItem`.
43+
If *length* is greater than zero, the returned list object's items are
44+
set to ``NULL``. Thus you cannot use abstract API functions such as
45+
:cfunc:`PySequence_SetItem` or expose the object to Python code before
46+
setting all items to a real object with :cfunc:`PyList_SetItem`.
4647

4748
.. versionchanged:: 2.5
4849
This function used an :ctype:`int` for *size*. This might require
@@ -65,12 +66,17 @@ List Objects
6566

6667
Macro form of :cfunc:`PyList_Size` without error checking.
6768

69+
.. versionchanged:: 2.5
70+
This macro returned an :ctype:`int`. This might require changes in your
71+
code for properly supporting 64-bit systems.
72+
6873

6974
.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)
7075

71-
Return the object at position *pos* in the list pointed to by *p*. The position
72-
must be positive, indexing from the end of the list is not supported. If *pos*
73-
is out of bounds, return *NULL* and set an :exc:`IndexError` exception.
76+
Return the object at position *pos* in the list pointed to by *p*. The
77+
position must be positive, indexing from the end of the list is not
78+
supported. If *pos* is out of bounds, return *NULL* and set an
79+
:exc:`IndexError` exception.
7480

7581
.. versionchanged:: 2.5
7682
This function used an :ctype:`int` for *index*. This might require
@@ -81,16 +87,20 @@ List Objects
8187

8288
Macro form of :cfunc:`PyList_GetItem` without error checking.
8389

90+
.. versionchanged:: 2.5
91+
This macro used an :ctype:`int` for *i*. This might require changes in
92+
your code for properly supporting 64-bit systems.
93+
8494

8595
.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)
8696

87-
Set the item at index *index* in list to *item*. Return ``0`` on success or
88-
``-1`` on failure.
97+
Set the item at index *index* in list to *item*. Return ``0`` on success
98+
or ``-1`` on failure.
8999

90100
.. note::
91101

92-
This function "steals" a reference to *item* and discards a reference to an item
93-
already in the list at the affected position.
102+
This function "steals" a reference to *item* and discards a reference to
103+
an item already in the list at the affected position.
94104

95105
.. versionchanged:: 2.5
96106
This function used an :ctype:`int` for *index*. This might require
@@ -99,21 +109,26 @@ List Objects
99109

100110
.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)
101111

102-
Macro form of :cfunc:`PyList_SetItem` without error checking. This is normally
103-
only used to fill in new lists where there is no previous content.
112+
Macro form of :cfunc:`PyList_SetItem` without error checking. This is
113+
normally only used to fill in new lists where there is no previous content.
104114

105115
.. note::
106116

107-
This function "steals" a reference to *item*, and, unlike
108-
:cfunc:`PyList_SetItem`, does *not* discard a reference to any item that it
109-
being replaced; any reference in *list* at position *i* will be leaked.
117+
This macro "steals" a reference to *item*, and, unlike
118+
:cfunc:`PyList_SetItem`, does *not* discard a reference to any item that
119+
is being replaced; any reference in *list* at position *i* will be
120+
leaked.
121+
122+
.. versionchanged:: 2.5
123+
This macro used an :ctype:`int` for *i*. This might require
124+
changes in your code for properly supporting 64-bit systems.
110125

111126

112127
.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)
113128

114-
Insert the item *item* into list *list* in front of index *index*. Return ``0``
115-
if successful; return ``-1`` and set an exception if unsuccessful. Analogous to
116-
``list.insert(index, item)``.
129+
Insert the item *item* into list *list* in front of index *index*. Return
130+
``0`` if successful; return ``-1`` and set an exception if unsuccessful.
131+
Analogous to ``list.insert(index, item)``.
117132

118133
.. versionchanged:: 2.5
119134
This function used an :ctype:`int` for *index*. This might require
@@ -122,16 +137,16 @@ List Objects
122137

123138
.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)
124139

125-
Append the object *item* at the end of list *list*. Return ``0`` if successful;
126-
return ``-1`` and set an exception if unsuccessful. Analogous to
127-
``list.append(item)``.
140+
Append the object *item* at the end of list *list*. Return ``0`` if
141+
successful; return ``-1`` and set an exception if unsuccessful. Analogous
142+
to ``list.append(item)``.
128143

129144

130145
.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)
131146

132-
Return a list of the objects in *list* containing the objects *between* *low*
133-
and *high*. Return *NULL* and set an exception if unsuccessful. Analogous to
134-
``list[low:high]``.
147+
Return a list of the objects in *list* containing the objects *between*
148+
*low* and *high*. Return *NULL* and set an exception if unsuccessful.
149+
Analogous to ``list[low:high]``.
135150

136151
.. versionchanged:: 2.5
137152
This function used an :ctype:`int` for *low* and *high*. This might
@@ -140,10 +155,10 @@ List Objects
140155

141156
.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)
142157

143-
Set the slice of *list* between *low* and *high* to the contents of *itemlist*.
144-
Analogous to ``list[low:high] = itemlist``. The *itemlist* may be *NULL*,
145-
indicating the assignment of an empty list (slice deletion). Return ``0`` on
146-
success, ``-1`` on failure.
158+
Set the slice of *list* between *low* and *high* to the contents of
159+
*itemlist*. Analogous to ``list[low:high] = itemlist``. The *itemlist* may
160+
be *NULL*, indicating the assignment of an empty list (slice deletion).
161+
Return ``0`` on success, ``-1`` on failure.
147162

148163
.. versionchanged:: 2.5
149164
This function used an :ctype:`int` for *low* and *high*. This might
@@ -152,8 +167,8 @@ List Objects
152167

153168
.. cfunction:: int PyList_Sort(PyObject *list)
154169

155-
Sort the items of *list* in place. Return ``0`` on success, ``-1`` on failure.
156-
This is equivalent to ``list.sort()``.
170+
Sort the items of *list* in place. Return ``0`` on success, ``-1`` on
171+
failure. This is equivalent to ``list.sort()``.
157172

158173

159174
.. cfunction:: int PyList_Reverse(PyObject *list)

‎Doc/c-api/marshal.rst‎

Lines changed: 36 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -5,24 +5,25 @@
55
Data marshalling support
66
========================
77

8-
These routines allow C code to work with serialized objects using the same data
9-
format as the :mod:`marshal` module. There are functions to write data into the
10-
serialization format, and additional functions that can be used to read the data
11-
back. Files used to store marshalled data must be opened in binary mode.
8+
These routines allow C code to work with serialized objects using the same
9+
data format as the :mod:`marshal` module. There are functions to write data
10+
into the serialization format, and additional functions that can be used to
11+
read the data back. Files used to store marshalled data must be opened in
12+
binary mode.
1213

1314
Numeric values are stored with the least significant byte first.
1415

15-
The module supports two versions of the data format: version 0 is the historical
16-
version, version 1 shares interned strings in the file, and upon unmarshalling.
17-
Version 2 uses a binary format for floating point numbers.
16+
The module supports two versions of the data format: version 0 is the
17+
historical version, version 1 shares interned strings in the file, and upon
18+
unmarshalling. Version 2 uses a binary format for floating point numbers.
1819
*Py_MARSHAL_VERSION* indicates the current file format (currently 2).
1920

2021

2122
.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)
2223

23-
Marshal a :ctype:`long` integer, *value*, to *file*. This will only write the
24-
least-significant 32 bits of *value*; regardless of the size of the native
25-
:ctype:`long` type. *version* indicates the file format.
24+
Marshal a :ctype:`long` integer, *value*, to *file*. This will only write
25+
the least-significant 32 bits of *value*; regardless of the size of the
26+
native :ctype:`long` type. *version* indicates the file format.
2627

2728

2829
.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)
@@ -40,24 +41,24 @@ Version 2 uses a binary format for floating point numbers.
4041
The following functions allow marshalled values to be read back in.
4142

4243
XXX What about error detection? It appears that reading past the end of the
43-
file will always result in a negative numeric value (where that's relevant), but
44-
it's not clear that negative values won't be handled properly when there's no
45-
error. What's the right way to tell? Should only non-negative values be written
46-
using these routines?
44+
file will always result in a negative numeric value (where that's relevant),
45+
but it's not clear that negative values won't be handled properly when there's
46+
no error. What's the right way to tell? Should only non-negative values be
47+
written using these routines?
4748

4849

4950
.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)
5051

51-
Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened for
52-
reading. Only a 32-bit value can be read in using this function, regardless of
53-
the native size of :ctype:`long`.
52+
Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened
53+
for reading. Only a 32-bit value can be read in using this function,
54+
regardless of the native size of :ctype:`long`.
5455

5556

5657
.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)
5758

58-
Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened for
59-
reading. Only a 16-bit value can be read in using this function, regardless of
60-
the native size of :ctype:`short`.
59+
Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened
60+
for reading. Only a 16-bit value can be read in using this function,
61+
regardless of the native size of :ctype:`short`.
6162

6263

6364
.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)
@@ -70,17 +71,22 @@ using these routines?
7071
.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)
7172

7273
Return a Python object from the data stream in a :ctype:`FILE\*` opened for
73-
reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function assumes
74-
that no further objects will be read from the file, allowing it to aggressively
75-
load file data into memory so that the de-serialization can operate from data in
76-
memory rather than reading a byte at a time from the file. Only use these
77-
variant if you are certain that you won't be reading anything else from the
78-
file. On error, sets the appropriate exception (:exc:`EOFError` or
79-
:exc:`TypeError`) and returns *NULL*.
74+
reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function
75+
assumes that no further objects will be read from the file, allowing it to
76+
aggressively load file data into memory so that the de-serialization can
77+
operate from data in memory rather than reading a byte at a time from the
78+
file. Only use these variant if you are certain that you won't be reading
79+
anything else from the file. On error, sets the appropriate exception
80+
(:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
8081

8182

8283
.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)
8384

84-
Return a Python object from the data stream in a character buffer containing
85-
*len* bytes pointed to by *string*. On error, sets the appropriate exception
86-
(:exc:`EOFError` or :exc:`TypeError`) and returns *NULL*.
85+
Return a Python object from the data stream in a character buffer
86+
containing *len* bytes pointed to by *string*. On error, sets the
87+
appropriate exception (:exc:`EOFError` or :exc:`TypeError`) and returns
88+
*NULL*.
89+
90+
.. versionchanged:: 2.5
91+
This function used an :ctype:`int` type for *len*. This might require
92+
changes in your code for properly supporting 64-bit systems.

‎Doc/c-api/objbuffer.rst‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -10,17 +10,26 @@ Buffer Protocol
1010

1111
Returns a pointer to a read-only memory location usable as character-based
1212
input. The *obj* argument must support the single-segment character buffer
13-
interface. On success, returns ``0``, sets *buffer* to the memory location and
14-
*buffer_len* to the buffer length. Returns ``-1`` and sets a :exc:`TypeError`
15-
on error.
13+
interface. On success, returns ``0``, sets *buffer* to the memory location
14+
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
15+
:exc:`TypeError` on error.
16+
17+
.. versionchanged:: 2.5
18+
This function used an :ctype:`int *` type for *buffer_len*. This might
19+
require changes in your code for properly supporting 64-bit systems.
1620

1721

1822
.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)
1923

20-
Returns a pointer to a read-only memory location containing arbitrary data. The
21-
*obj* argument must support the single-segment readable buffer interface. On
22-
success, returns ``0``, sets *buffer* to the memory location and *buffer_len* to
23-
the buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
24+
Returns a pointer to a read-only memory location containing arbitrary data.
25+
The *obj* argument must support the single-segment readable buffer
26+
interface. On success, returns ``0``, sets *buffer* to the memory location
27+
and *buffer_len* to the buffer length. Returns ``-1`` and sets a
28+
:exc:`TypeError` on error.
29+
30+
.. versionchanged:: 2.5
31+
This function used an :ctype:`int *` type for *buffer_len*. This might
32+
require changes in your code for properly supporting 64-bit systems.
2433

2534

2635
.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)
@@ -32,6 +41,11 @@ Buffer Protocol
32< BDA5 /td>41
.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)
3342

3443
Returns a pointer to a writable memory location. The *obj* argument must
35-
support the single-segment, character buffer interface. On success, returns
36-
``0``, sets *buffer* to the memory location and *buffer_len* to the buffer
37-
length. Returns ``-1`` and sets a :exc:`TypeError` on error.
44+
support the single-segment, character buffer interface. On success,
45+
returns ``0``, sets *buffer* to the memory location and *buffer_len* to the
46+
buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.
47+
48+
.. versionchanged:: 2.5
49+
This function used an :ctype:`int *` type for *buffer_len*. This might
50+
require changes in your code for properly supporting 64-bit systems.
51+

‎Doc/c-api/sequence.rst‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -178,6 +178,10 @@ Sequence Protocol
178178
Return the *i*th element of *o*, assuming that *o* was returned by
179179
:cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.
180180

181+
.. versionchanged:: 2.5
182+
This function used an :ctype:`int` type for *i*. This might require
183+
changes in your code for properly supporting 64-bit systems.
184+
181185

182186
.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)
183187

@@ -196,6 +200,10 @@ Sequence Protocol
196200
:cfunc:`PySequence_Check(o)` is true and without adjustment for negative
197201
indices.
198202

203+
.. versionchanged:: 2.5
204+
This function used an :ctype:`int` type for *i*. This might require
205+
changes in your code for properly supporting 64-bit systems.
206+
199207

200208
.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)
201209

0 commit comments

Comments
 (0)
0