Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit bd87552

Browse files
ashemedaiashemedai
committed
Merged revisions 71898-71900,71910,71914-71919 via svnmerge from
svn+ssh://[email protected]/python/trunk ........ 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. ........
1 parent 939c178 commit bd87552

14 files changed

Lines changed: 312 additions & 156 deletions

‎Doc/c-api/allocation.rst‎

Lines changed: 26 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -11,13 +11,18 @@ Allocating Objects on the Heap
1111

1212
.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)
1313

14+
.. versionchanged:: 2.5
15+
This function used an :ctype:`int` type for *size*. This might require
16+
changes in your code for properly supporting 64-bit systems.
17+
1418

1519
.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)
1620

17-
Initialize a newly-allocated object *op* with its type and initial reference.
18-
Returns the initialized object. If *type* indicates that the object
19-
participates in the cyclic garbage detector, it is added to the detector's set
20-
of observed objects. Other fields of the object are not affected.
21+
Initialize a newly-allocated object *op* with its type and initial
22+
reference. Returns the initialized object. If *type* indicates that the
23+
object participates in the cyclic garbage detector, it is added to the
24+
detector's set of observed objects. Other fields of the object are not
25+
affected.
2126

2227

2328
.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)
@@ -28,30 +33,32 @@ Allocating Objects on the Heap
2833

2934
.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)
3035

31-
Allocate a new Python object using the C structure type *TYPE* and the Python
32-
type object *type*. Fields not defined by the Python object header are not
33-
initialized; the object's reference count will be one. The size of the memory
34-
allocation is determined from the :attr:`tp_basicsize` field of the type object.
36+
Allocate a new Python object using the C structure type *TYPE* and the
37+
Python type object *type*. Fields not defined by the Python object header
38+
are not initialized; the object's reference count will be one. The size of
39+
the memory allocation is determined from the :attr:`tp_basicsize` field of
40+
the type object.
3541

3642

3743
.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)
3844

39-
Allocate a new Python object using the C structure type *TYPE* and the Python
40-
type object *type*. Fields not defined by the Python object header are not
41-
initialized. The allocated memory allows for the *TYPE* structure plus *size*
42-
fields of the size given by the :attr:`tp_itemsize` field of *type*. This is
43-
useful for implementing objects like tuples, which are able to determine their
44-
size at construction time. Embedding the array of fields into the same
45-
allocation decreases the number of allocations, improving the memory management
46-
efficiency.
45+
Allocate a new Python object using the C structure type *TYPE* and the
46+
Python type object *type*. Fields not defined by the Python object header
47+
are not initialized. The allocated memory allows for the *TYPE* structure
48+
plus *size* fields of the size given by the :attr:`tp_itemsize` field of
49+
*type*. This is useful for implementing objects like tuples, which are
50+
able to determine their size at construction time. Embedding the array of
51+
fields into the same allocation decreases the number of allocations,
52+
improving the memory management efficiency.
4753

4854

4955
.. cfunction:: void PyObject_Del(PyObject *op)
5056

5157
Releases memory allocated to an object using :cfunc:`PyObject_New` or
52-
:cfunc:`PyObject_NewVar`. This is normally called from the :attr:`tp_dealloc`
53-
handler specified in the object's type. The fields of the object should not be
54-
accessed after this call as the memory is no longer a valid Python object.
58+
:cfunc:`PyObject_NewVar`. This is normally called from the
59+
:attr:`tp_dealloc` handler specified in the object's type. The fields of
60+
the object should not be accessed after this call as the memory is no
61+
longer a valid Python object.
5562

5663

5764
.. cvar:: PyObject _Py_NoneStruct

‎Doc/c-api/arg.rst‎

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -278,10 +278,10 @@ variable(s) whose address should be passed.
278278

279279
``w#`` (read-write character buffer) [char \*, int]
280280
Like ``s#``, but accepts any object which implements the read-write buffer
281-
interface. The :ctype:`char \*` variable is set to point to the first byte of
282-
the buffer, and the :ctype:`int` is set to the length of the buffer. Only
283-
single-segment buffer objects are accepted; :exc:`TypeError` is raised for all
284-
others.
281+
interface. The :ctype:`char \*` variable is set to point to the first byte
282+
of the buffer, and the :ctype:`int` is set to the length of the buffer.
283+
Only single-segment buffer objects are accepted; :exc:`TypeError` is raised
284+
for all others.
285285

286286
``(items)`` (tuple) [*matching-items*]
287287
The object must be a Python sequence whose length is the number of format units
@@ -406,6 +406,10 @@ and the following format units are left untouched.
406406

407407
PyArg_ParseTuple(args, "O|O:ref", &object, &callback)
408408

409+
.. versionchanged:: 2.5
410+
This function used an :ctype:`int` type for *min* and *max*. This might
411+
require changes in your code for properly supporting 64-bit systems.
412+
409413

410414
.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)
411415

‎Doc/c-api/buffer.rst‎

Lines changed: 30 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -15,8 +15,8 @@ Buffer Objects
1515

1616
Python objects implemented in C can export a "buffer interface." These
1717
functions can be used by an object to expose its data in a raw, byte-oriented
18-
format. Clients of the object can use the buffer interface to access the object
19-
data directly, without needing to copy it first.
18+
format. Clients of the object can use the buffer interface to access the
19+
object data directly, without needing to copy it first.
2020

2121
Two examples of objects that support the buffer interface are bytes and
2222
arrays. The bytes object exposes the character contents in the buffer
@@ -61,9 +61,9 @@ could be used to pass around structured data in its native, in-memory format.
6161
.. cmember:: const char *format
6262
:noindex:
6363

64-
A *NULL* terminated string in :mod:`struct` module style syntax giving the
65-
contents of the elements available through the buffer. If this is *NULL*,
66-
``"B"`` (unsigned bytes) is assumed.
64+
A *NULL* terminated string in :mod:`struct` module style syntax giving
65+
the contents of the elements available through the buffer. If this is
66+
*NULL*, ``"B"`` (unsigned bytes) is assumed.
6767

6868
.. cmember:: int ndim
6969

@@ -113,11 +113,11 @@ could be used to pass around structured data in its native, in-memory format.
113113
.. cmember:: Py_ssize_t itemsize
114114

115115
This is a storage for the itemsize (in bytes) of each element of the
116-
shared memory. It is technically un-necessary as it can be obtained using
117-
:cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know this
118-
information without parsing the format string and it is necessary to know
119-
the itemsize for proper interpretation of striding. Therefore, storing it
120-
is more convenient and faster.
116+
shared memory. It is technically un-necessary as it can be obtained
117+
using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know
118+
this information without parsing the format string and it is necessary
119+
to know the itemsize for proper interpretation of striding. Therefore,
120+
storing it is more convenient and faster.
121121

122122
.. cmember:: void *internal
123123

@@ -140,20 +140,20 @@ Buffer related functions
140140
.. cfunction:: int PyObject_GetBuffer(PyObject *obj, PyObject *view, int flags)
141141

142142
Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must
143-
never be *NULL*. The *flags* argument is a bit field indicating what kind
144-
of buffer the caller is prepared to deal with and therefore what kind of
145-
buffer the exporter is allowed to return. The buffer interface allows for
146-
complicated memory sharing possibilities, but some caller may not be able
147-
to handle all the complexibity but may want to see if the exporter will
148-
let them take a simpler view to its memory.
143+
never be *NULL*. The *flags* argument is a bit field indicating what
144+
kind of buffer the caller is prepared to deal with and therefore what
145+
kind of buffer the exporter is allowed to return. The buffer interface
146+
allows for complicated memory sharing possibilities, but some caller may
147+
not be able to handle all the complexibity but may want to see if the
148+
exporter will let them take a simpler view to its memory.
149149

150150
Some exporters may not be able to share memory in every possible way and
151151
may need to raise errors to signal to some consumers that something is
152152
just not possible. These errors should be a :exc:`BufferError` unless
153-
there is another error that is actually causing the problem. The exporter
154-
can use flags information to simplify how much of the :cdata:`Py_buffer`
155-
structure is filled in with non-default values and/or raise an error if
156-
the object can't support a simpler view of its memory.
153+
there is another error that is actually causing the problem. The
154+
exporter can use flags information to simplify how much of the
155+
:cdata:`Py_buffer` structure is filled in with non-default values and/or
156+
raise an error if the object can't support a simpler view of its memory.
157157

158158
0 is returned on success and -1 on error.
159159

@@ -264,16 +264,16 @@ Buffer related functions
264264

265265
.. cfunction:: int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len, char fortran)
266266

267-
Copy *len* bytes of data pointed to by the contiguous chunk of memory pointed
268-
to by *buf* into the buffer exported by obj. The buffer must of course be
269-
writable. Return 0 on success and return -1 and raise an error on failure.
270-
If the object does not have a writable buffer, then an error is raised. If
271-
*fortran* is ``'F'``, then if the object is multi-dimensional, then the data
272-
will be copied into the array in Fortran-style (first dimension varies the
273-
fastest). If *fortran* is ``'C'``, then the data will be copied into the
274-
array in C-style (last dimension varies the fastest). If *fortran* is
275-
``'A'``, then it does not matter and the copy will be made in whatever way is
276-
more efficient.
267+
Copy *len* bytes of data pointed to by the contiguous chunk of memory
268+
pointed to by *buf* into the buffer exported by obj. The buffer must of
269+
course be writable. Return 0 on success and return -1 and raise an error
270+
on failure. If the object does not have a writable buffer, then an error
271+
is raised. If *fortran* is ``'F'``, then if the object is
272+
multi-dimensional, then the data will be copied into the array in
273+
Fortran-style (first dimension varies the fastest). If *fortran* is
274+
``'C'``, then the data will be copied into the array in C-style (last
275+
dimension varies the fastest). If *fortran* is ``'A'``, then it does not
276+
matter and the copy will be made in whatever way is more efficient.
277277

278278

279279
.. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)

0 commit comments

Comments
 (0)