pytho****@googl*****
pytho****@googl*****
2011年 3月 20日 (日) 00:45:33 JST
2 new revisions: Revision: 913f71bf00a0 Author: Naoki INADA <inada****@klab*****> Date: Sat Mar 19 08:30:15 2011 Log: c-api, distutils, documenting, extending, install, reference,... http://code.google.com/p/python-doc-ja/source/detail?r=913f71bf00a0 Revision: 013b5348d951 Author: Naoki INADA <inada****@klab*****> Date: Sat Mar 19 08:34:47 2011 Log: merge http://code.google.com/p/python-doc-ja/source/detail?r=013b5348d951 ============================================================================== Revision: 913f71bf00a0 Author: Naoki INADA <inada****@klab*****> Date: Sat Mar 19 08:30:15 2011 Log: c-api, distutils, documenting, extending, install, reference, using の diff を追加. http://code.google.com/p/python-doc-ja/source/detail?r=913f71bf00a0 Added: /c-api/diff/allocation.rst.diff /c-api/diff/allocation.rst.html /c-api/diff/arg.rst.diff /c-api/diff/arg.rst.html /c-api/diff/buffer.rst.diff /c-api/diff/buffer.rst.html /c-api/diff/bytearray.rst.diff /c-api/diff/bytearray.rst.html /c-api/diff/datetime.rst.diff /c-api/diff/datetime.rst.html /c-api/diff/dict.rst.diff /c-api/diff/dict.rst.html /c-api/diff/exceptions.rst.diff /c-api/diff/exceptions.rst.html /c-api/diff/float.rst.diff /c-api/diff/float.rst.html /c-api/diff/gcsupport.rst.diff /c-api/diff/gcsupport.rst.html /c-api/diff/import.rst.diff /c-api/diff/import.rst.html /c-api/diff/init.rst.diff /c-api/diff/init.rst.html /c-api/diff/int.rst.diff /c-api/diff/int.rst.html /c-api/diff/intro.rst.diff /c-api/diff/intro.rst.html /c-api/diff/list.rst.diff /c-api/diff/list.rst.html /c-api/diff/long.rst.diff /c-api/diff/long.rst.html /c-api/diff/mapping.rst.diff /c-api/diff/mapping.rst.html /c-api/diff/marshal.rst.diff /c-api/diff/marshal.rst.html /c-api/diff/method.rst.diff /c-api/diff/method.rst.html /c-api/diff/objbuffer.rst.diff /c-api/diff/objbuffer.rst.html /c-api/diff/object.rst.diff /c-api/diff/object.rst.html /c-api/diff/sequence.rst.diff /c-api/diff/sequence.rst.html /c-api/diff/set.rst.diff /c-api/diff/set.rst.html /c-api/diff/slice.rst.diff /c-api/diff/slice.rst.html /c-api/diff/string.rst.diff /c-api/diff/string.rst.html /c-api/diff/structures.rst.diff /c-api/diff/structures.rst.html /c-api/diff/sys.rst.diff /c-api/diff/sys.rst.html /c-api/diff/tuple.rst.diff /c-api/diff/tuple.rst.html /c-api/diff/type.rst.diff /c-api/diff/type.rst.html /c-api/diff/typeobj.rst.diff /c-api/diff/typeobj.rst.html /c-api/diff/unicode.rst.diff /c-api/diff/unicode.rst.html /c-api/diff/weakref.rst.diff /c-api/diff/weakref.rst.html /distutils/diff/apiref.rst.diff /distutils/diff/apiref.rst.html /distutils/diff/builtdist.rst.diff /distutils/diff/builtdist.rst.html /distutils/diff/extending.rst.diff /distutils/diff/extending.rst.html /distutils/diff/setupscript.rst.diff /distutils/diff/setupscript.rst.html /distutils/diff/sourcedist.rst.diff /distutils/diff/sourcedist.rst.html /documenting/diff/index.rst.diff /documenting/diff/index.rst.html /documenting/diff/markup.rst.diff /documenting/diff/markup.rst.html /documenting/diff/style.rst.diff /documenting/diff/style.rst.html /extending/diff/extending.rst.diff /extending/diff/extending.rst.html /extending/diff/newtypes.rst.diff /extending/diff/newtypes.rst.html /install/diff/index.rst.diff /install/diff/index.rst.html /reference/diff/compound_stmts.rst.diff /reference/diff/compound_stmts.rst.html /reference/diff/datamodel.rst.diff /reference/diff/datamodel.rst.html /reference/diff/executionmodel.rst.diff /reference/diff/executionmodel.rst.html /reference/diff/expressions.rst.diff /reference/diff/expressions.rst.html /reference/diff/lexical_analysis.rst.diff /reference/diff/lexical_analysis.rst.html /reference/diff/simple_stmts.rst.diff /reference/diff/simple_stmts.rst.html /using/diff/cmdline.rst.diff /using/diff/cmdline.rst.html /using/diff/mac.rst.diff /using/diff/mac.rst.html /using/diff/unix.rst.diff /using/diff/unix.rst.html /using/diff/windows.rst.diff /using/diff/windows.rst.html ======================================= --- /dev/null +++ /c-api/diff/allocation.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,165 @@ +--- r262/c-api/allocation.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/allocation.rst 2009-04-29 17:00:05.894850000 +0900 +@@ -2,103 +2,121 @@ + + .. _allocating-objects: + + Allocating Objects on the Heap + ============================== + + + .. cfunction:: PyObject* _PyObject_New(PyTypeObject *type) + + + .. 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) + + 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. ======================================= --- /dev/null +++ /c-api/diff/allocation.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,148 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to2__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/allocation.rst => r266/c-api/allocation.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to2__0"></td><td class="diff_header" id="from2_6">6</td><td nowrap="nowrap">==============================</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_7">7</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_8">8</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_9">9</td><td nowrap="nowrap">.. cfunction:: PyObject* _PyObject_New(PyTypeObject *type)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_10">10</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_11">11</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_12">12</td><td nowrap="nowrap">.. cfunction:: PyVarObject* _PyObject_NewVar(PyTypeObject *type, Py_ssize_t size)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_13">13</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__1">n</a></td><td class="diff_header" id="to2_14">14+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_15">15+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *size*. This might require</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to2__1"></td><td class="diff_header" id="to2_16">16+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_17">17+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from2_14">14</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_15">15</td><td nowrap="nowrap">.. cfunction:: void _PyObject_Del(PyObject *op)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_16">16</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_17">17</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_18">18</td><td nowrap="nowrap">.. cfunction:: PyObject* PyObject_Init(PyObject *op, PyTypeObject *type)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_19">19</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__2">n</a></td><td class="diff_header" id="from2_20">20-</td><td nowrap="nowrap"> Initialize a newly-allocated object *op* with its type and initial<span class="diff_sub"> reference.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__2">n</a></td><td class="diff_header" id="to2_24">24+</td><td nowrap="nowrap"> Initialize a newly-allocated object *op* with its type and initial</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_21">21-</td><td nowrap="nowrap"> Returns the initialized object. If *type* indicates that the<span class="diff_sub"> object</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_25">25+</td><td nowrap="nowrap"> <span class="diff_add"> reference.</span> Returns the initialized object. If *type* indicates that the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_22">22-</td><td nowrap="nowrap"> participates in the cyclic garbage detector, it is added to the<span class="diff_sub"> detector's set</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_26">26+</td><td nowrap="nowrap"> <span class="diff_add"> object</span> participates in the cyclic garbage detector, it is added to the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_23">23-</td><td nowrap="nowrap"> of observed objects. Other fields of the object are not<span class="diff_sub"> affected.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_27">27+</td><td nowrap="nowrap"> <span class="diff_add"> detector's set</span> of observed objects. Other fields of the object are not</td></tr> +<tr><td class="diff_next" id="difflib_chg_to2__2"></td><td class="diff_header" id="to2_28">28+</td><td nowrap="nowrap"><span class="diff_add"> affected.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from2_24">24</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_25">25</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_26">26</td><td nowrap="nowrap">.. cfunction:: PyVarObject* PyObject_InitVar(PyVarObject *op, PyTypeObject *type, Py_ssize_t size)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_27">27</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_28">28</td><td nowrap="nowrap"> This does everything :cfunc:`PyObject_Init` does, and also initializes the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_29">29</td><td nowrap="nowrap"> length information for a variable-size object.</td></tr> <tr><td class="diff_next" id="difflib_chg_to2__3"></td><td class="diff_header" id="from2_30">30</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__3">n</a></td><td class="diff_header" id="to2_36">36+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_37">37+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *size*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_38">38+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_39">39+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from2_31">31</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_32">32</td><td nowrap="nowrap">.. cfunction:: TYPE* PyObject_New(TYPE, PyTypeObject *type)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_33">33</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__4">n</a></td><td class="diff_header" id="from2_34">34-</td><td nowrap="nowrap"> Allocate a new Python object using the C structure type *TYPE* and the<span class="diff_sub"> Python</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__4">n</a></td><td class="diff_header" id="to2_43">43+</td><td nowrap="nowrap"> Allocate a new Python object using the C structure type *TYPE* and the</td></tr> +<tr><td class="diff_next" id="difflib_chg_to2__4"></td><td class="diff_header" id="from2_35">35-</td><td nowrap="nowrap"> type object *type*. Fields not defined by the Python object header<span class="diff_sub"> are not</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to2__4"></td><td class="diff_header" id="to2_44">44+</td><td nowrap="nowrap"> <span class="diff_add"> Python</span> type object *type*. Fields not defined by the Python object header</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_36">36-</td><td nowrap="nowrap"> initialized; the object's reference count will be one. The size of<span class="diff_sub"> the memory</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_45">45+</td><td nowrap="nowrap"> <span class="diff_add"> are not</span> initialized; the object's reference count will be one. The size of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_37">37-</td><td nowrap="nowrap"> allocation is determined from the :attr:`tp_basicsize` field of<span class="diff_sub"> the type object.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_46">46+</td><td nowrap="nowrap"> <span class="diff_add"> the memory</span> allocation is determined from the :attr:`tp_basicsize` field of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_47">47+</td><td nowrap="nowrap"><span class="diff_add"> the type object.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from2_38">38</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_39">39</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_40">40</td><td nowrap="nowrap">.. cfunction:: TYPE* PyObject_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_41">41</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__5">n</a></td><td class="diff_header" id="from2_42">42-</td><td nowrap="nowrap"> Allocate a new Python object using the C structure type *TYPE* and the<span class="diff_sub"> Python</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__5">n</a></td><td class="diff_header" id="to2_52">52+</td><td nowrap="nowrap"> Allocate a new Python object using the C structure type *TYPE* and the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_43">43-</td><td nowrap="nowrap"> type object *type*. Fields not defined by the Python object header<span class="diff_sub"> are not</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_53">53+</td><td nowrap="nowrap"> <span class="diff_add"> Python</span> type object *type*. Fields not defined by the Python object header</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_44">44-</td><td nowrap="nowrap"> initialized. The allocated memory allows for the *TYPE* structure<span class="diff_sub"> plus *size*</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_54">54+</td><td nowrap="nowrap"> <span class="diff_add"> are not</span> initialized. The allocated memory allows for the *TYPE* structure</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_45">45-</td><td nowrap="nowrap"> fields of the size given by the :attr:`tp_itemsize` field of<span class="diff_sub"> *type*. This is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_55">55+</td><td nowrap="nowrap"> <span class="diff_add"> plus *size*</span> fields of the size given by the :attr:`tp_itemsize` field of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_46">46-</td><td nowrap="nowrap"><span class="diff_sub"> useful for implementing objects like tuples, which are able to determine their</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_56">56+</td><td nowrap="nowrap"><span class="diff_add"> *type*. This is useful for implementing objects like tuples, which are</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_47">47-</td><td nowrap="nowrap"><span class="diff_sub"> size at construction time. Embedding the array of fields into the same</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_57">57+</td><td nowrap="nowrap"><span class="diff_add"> able to determine their size at construction time. Embedding the array of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_48">48-</td><td nowrap="nowrap"><span class="diff_sub"> allocation decreases the number of allocations, improving the memory management</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_58">58+</td><td nowrap="nowrap"><span class="diff_add"> fields into the same allocation decreases the number of allocations,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_49">49-</td><td nowrap="nowrap"><span class="diff_sub"> efficiency.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_59">59+</td><td nowrap="nowrap"><span class="diff_add"> improving the memory management efficiency.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_60">60+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to2__5"></td><td class="diff_header" id="to2_61">61+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_62">62+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *size*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_63">63+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from2_50">50</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_51">51</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_52">52</td><td nowrap="nowrap">.. cfunction:: void PyObject_Del(PyObject *op)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_53">53</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_54">54</td><td nowrap="nowrap"> Releases memory allocated to an object using :cfunc:`PyObject_New` or</td></tr><tr><td class="diff_next" id="difflib_chg_to2__6"><a href="#difflib_chg_to2__6">n</a></td><td class="diff_header" id="from2_55">55-</td><td nowrap="nowrap"> :cfunc:`PyObject_NewVar`. This is normally called from the<span class="diff_sub"> :attr:`tp_dealloc`</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to2__6"><a href="#difflib_chg_to2__6">n</a></td><td class="diff_header" id="to2_69">69+</td><td nowrap="nowrap"> :cfunc:`PyObject_NewVar`. This is normally called from the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_56">56-</td><td nowrap="nowrap"><span class="diff_sub"> handler specified in the object's type. The fields of the object should not be</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_70">70+</td><td nowrap="nowrap"><span class="diff_add"> :attr:`tp_dealloc` handler specified in the object's type. The fields of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_57">57-</td><td nowrap="nowrap"><span class="diff_sub"> accessed after this call as the memory is no longer a valid Python object.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_71">71+</td><td nowrap="nowrap"><span class="diff_add"> the object should not be accessed after this call as the memory is no</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_72">72+</td><td nowrap="nowrap"><span class="diff_add"> longer a valid Python object.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to2__7"></td><td class="diff_header" id="from2_58">58</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_59">59</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_60">60</td><td nowrap="nowrap">.. cfunction:: PyObject* Py_InitModule(char *name, PyMethodDef *methods)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_61">61</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__7">n</a></td><td class="diff_header" id="from2_62">62-</td><td nowrap="nowrap"> Create a new module object based on a name and table of functions,<span class="diff_sub"> returning the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__7">n</a></td><td class="diff_header" id="to2_77">77+</td><td nowrap="nowrap"> Create a new module object based on a name and table of functions,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_63">63-</td><td nowrap="nowrap"> new module object.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_78">78+</td><td nowrap="nowrap"> <span class="diff_add"> returning the</span> new module object.</td></tr> + <tr><td class="diff_next" id="difflib_chg_to2__8"></td><td class="diff_header" id="from2_64">64</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_65">65</td><td nowrap="nowrap"> .. versionchanged:: 2.3</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__8">n</a></td><td class="diff_header" id="from2_66">66-</td><td nowrap="nowrap"> Older versions of Python did not support *NULL* as the value for the<span class="diff_sub"> *methods*</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__8">n</a></td><td class="diff_header" id="to2_81">81+</td><td nowrap="nowrap"> Older versions of Python did not support *NULL* as the value for the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_67">67-</td><td nowrap="nowrap"> argument.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_82">82+</td><td nowrap="nowrap"> <span class="diff_add"> *methods*</span> argument.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from2_68">68</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to2__9"></td><td class="diff_header" id="from2_69">69</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_70">70</td><td nowrap="nowrap">.. cfunction:: PyObject* Py_InitModule3(char *name, PyMethodDef *methods, char *doc)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_71">71</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__9">n</a></td><td class="diff_header" id="from2_72">72-</td><td nowrap="nowrap"> Create a new module object based on a name and table of functions,<span class="diff_sub"> returning the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__9">n</a></td><td class="diff_header" id="to2_87">87+</td><td nowrap="nowrap"> Create a new module object based on a name and table of functions,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_73">73-</td><td nowrap="nowrap"> new module object. If *doc* is non-*NULL*, it will be used<span class="diff_sub"> to define the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_88">88+</td><td nowrap="nowrap"> <span class="diff_add"> returning the</span> new module object. If *doc* is non-*NULL*, it will be used</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_74">74-</td><td nowrap="nowrap"> docstring for the module.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_89">89+</td><td nowrap="nowrap"> <span class="diff_add"> to define the</span> docstring for the module.</td></tr> + <tr><td class="diff_next" id="difflib_chg_to2__10"></td><td class="diff_header" id="from2_75">75</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_76">76</td><td nowrap="nowrap"> .. versionchanged:: 2.3</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__10">n</a></td><td class="diff_header" id="from2_77">77-</td><td nowrap="nowrap"> Older versions of Python did not support *NULL* as the value for the<span class="diff_sub"> *methods*</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__10">n</a></td><td class="diff_header" id="to2_92">92+</td><td nowrap="nowrap"> Older versions of Python did not support *NULL* as the value for the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_78">78-</td><td nowrap="nowrap"> argument.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_93">93+</td><td nowrap="nowrap"> <span class="diff_add"> *methods*</span> argument.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from2_79">79</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_80">80</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_81">81</td><td nowrap="nowrap">.. cfunction:: PyObject* Py_InitModule4(char *name, PyMethodDef *methods, char *doc, PyObject *self, int apiver)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_82">82</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__11">n</a></td><td class="diff_header" id="from2_83">83-</td><td nowrap="nowrap"> Create a new module object based on a name and table of functions,<span class="diff_sub"> returning the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__11">n</a></td><td class="diff_header" id="to2_98">98+</td><td nowrap="nowrap"> Create a new module object based on a name and table of functions,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_84">84-</td><td nowrap="nowrap"> new module object. If *doc* is non-*NULL*, it will be used<span class="diff_sub"> to define the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_99">99+</td><td nowrap="nowrap"> <span class="diff_add"> returning the</span> new module object. If *doc* is non-*NULL*, it will be used</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_85">85-</td><td nowrap="nowrap"> docstring for the module. If *self* is non-*NULL*, it will<span class="diff_sub"> passed to the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_100">100+</td><td nowrap="nowrap"> <span class="diff_add"> to define the</span> docstring for the module. If *self* is non-*NULL*, it will</td></tr> +<tr><td class="diff_next" id="difflib_chg_to2__11"></td><td class="diff_header" id="from2_86">86-</td><td nowrap="nowrap"> functions of the module as their (otherwise *NULL*) first<span class="diff_sub"> parameter. (This was</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to2__11"></td><td class="diff_header" id="to2_101">101+</td><td nowrap="nowrap"> <span class="diff_add"> passed to the</span> functions of the module as their (otherwise *NULL*) first</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_87">87-</td><td nowrap="nowrap"><span class="diff_sub"> added as an experimental feature, and there are no known uses in the current</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_102">102+</td><td nowrap="nowrap"><span class="diff_add"> parameter. (This was added as an experimental feature, and there are no</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_88">88-</td><td nowrap="nowrap"><span class="diff_sub"> version of Python.) For *apiver*, the only value which should be passed is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_103">103+</td><td nowrap="nowrap"><span class="diff_add"> known uses in the current version of Python.) For *apiver*, the only value</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_89">89-</td><td nowrap="nowrap"><span class="diff_sub"> defined by the constant :const:`PYTHON_API_VERSION`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_104">104+</td><td nowrap="nowrap"><span class="diff_add"> which should be passed is defined by the constant</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_105">105+</td><td nowrap="nowrap"><span class="diff_add"> :const:`PYTHON_API_VERSION`.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to2__12"></td><td class="diff_header" id="from2_90">90</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_91">91</td><td nowrap="nowrap"> .. note::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_92">92</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__12">n</a></td><td class="diff_header" id="from2_93">93-</td><td nowrap="nowrap"> Most uses of this function should probably be using the<span class="diff_sub"> :cfunc:`Py_InitModule3`</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__12">n</a></td><td class="diff_header" id="to2_109">109+</td><td nowrap="nowrap"> Most uses of this function should probably be using the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_94">94-</td><td nowrap="nowrap"> instead; only use this if you are sure you need<span class="diff_sub"> it.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_110">110+</td><td nowrap="nowrap"> <span class="diff_add"> :cfunc:`Py_InitModule3`</span> instead; only use this if you are sure you need</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_111">111+</td><td nowrap="nowrap"><span class="diff_add"> it.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to2__13"></td><td class="diff_header" id="from2_95">95</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_96">96</td><td nowrap="nowrap"> .. versionchanged:: 2.3</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__13">n</a></td><td class="diff_header" id="from2_97">97-</td><td nowrap="nowrap"> Older versions of Python did not support *NULL* as the value for the<span class="diff_sub"> *methods*</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__13">n</a></td><td class="diff_header" id="to2_114">114+</td><td nowrap="nowrap"> Older versions of Python did not support *NULL* as the value for the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_98">98-</td><td nowrap="nowrap"> argument.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_115">115+</td><td nowrap="nowrap"> <span class="diff_add"> *methods*</span> argument.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from2_99">99</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_100">100</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_101">101</td><td nowrap="nowrap">.. cvar:: PyObject _Py_NoneStruct</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from2_102">102</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to2__top">t</a></td><td class="diff_header" id="from2_103">103-</td><td nowrap="nowrap"> Object which is visible in Python as ``None``. This should only be<span class="diff_sub"> accessed</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to2__top">t</a></td><td class="diff_header" id="to2_120">120+</td><td nowrap="nowrap"> Object which is visible in Python as ``None``. This should only be</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from2_104">104-</td><td nowrap="nowrap"> using the ``Py_None`` macro, which evaluates to a pointer to this<span class="diff_sub"> object.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_121">121+</td><td nowrap="nowrap"> <span class="diff_add"> accessed</span> using the ``Py_None`` macro, which evaluates to a pointer to this</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to2_122">122+</td><td nowrap="nowrap"><span class="diff_add"> object.</span></td></tr> + </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/arg.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,817 @@ +--- r262/c-api/arg.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/arg.rst 2010-04-03 17:42:35.767391000 +0900 +@@ -1,542 +1,559 @@ + .. highlightlang:: c + + .. _arg-parsing: + + Parsing arguments and building values + ===================================== + + These functions are useful when creating your own extensions functions and + methods. Additional information and examples are available in + :ref:`extending-index`. + + The first three of these functions described, :cfunc:`PyArg_ParseTuple`, +-:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use *format +-strings* which are used to tell the function about the expected arguments. The +-format strings use the same syntax for each of these functions. ++:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use ++*format strings* which are used to tell the function about the expected ++arguments. The format strings use the same syntax for each of these ++functions. + + A format string consists of zero or more "format units." A format unit +-describes one Python object; it is usually a single character or a parenthesized +-sequence of format units. With a few exceptions, a format unit that is not a +-parenthesized sequence normally corresponds to a single address argument to +-these functions. In the following description, the quoted form is the format +-unit; the entry in (round) parentheses is the Python object type that matches +-the format unit; and the entry in [square] brackets is the type of the C +-variable(s) whose address should be passed. +- +-``s`` (string or Unicode object) [const char \*] +- Convert a Python string or Unicode object to a C pointer to a character string. +- You must not provide storage for the string itself; a pointer to an existing +- string is stored into the character pointer variable whose address you pass. +- The C string is NUL-terminated. The Python string must not contain embedded NUL +- bytes; if it does, a :exc:`TypeError` exception is raised. Unicode objects are +- converted to C strings using the default encoding. If this conversion fails, a +- :exc:`UnicodeError` is raised. ++describes one Python object; it is usually a single character or a ++parenthesized sequence of format units. With a few exceptions, a format unit ++that is not a parenthesized sequence normally corresponds to a single address ++argument to these functions. In the following description, the quoted form is ++the format unit; the entry in (round) parentheses is the Python object type ++that matches the format unit; and the entry in [square] brackets is the type ++of the C variable(s) whose address should be passed. ++ ++``s`` (string or Unicode) [const char \*] ++ Convert a Python string or Unicode object to a C pointer to a character ++ string. You must not provide storage for the string itself; a pointer to ++ an existing string is stored into the character pointer variable whose ++ address you pass. The C string is NUL-terminated. The Python string must ++ not contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is ++ raised. Unicode objects are converted to C strings using the default ++ encoding. If this conversion fails, a :exc:`UnicodeError` is raised. + + ``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :ctype:`Py_ssize_t`, see below)] +- This variant on ``s`` stores into two C variables, the first one a pointer to a +- character string, the second one its length. In this case the Python string may +- contain embedded null bytes. Unicode objects pass back a pointer to the default +- encoded string version of the object if such a conversion is possible. All +- other read-buffer compatible objects pass back a reference to the raw internal +- data representation. +- +- Starting with Python 2.5 the type of the length argument can be +- controlled by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before +- including :file:`Python.h`. If the macro is defined, length is a +- :ctype:`Py_ssize_t` rather than an int. +- +-``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer \*] +- Similar to ``s#``, this code fills a Py_buffer structure provided by the caller. +- The buffer gets locked, so that the caller can subsequently use the buffer even +- inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is responsible for calling +- ``PyBuffer_Release`` with the structure after it has processed the data. ++ This variant on ``s`` stores into two C variables, the first one a pointer ++ to a character string, the second one its length. In this case the Python ++ string may contain embedded null bytes. Unicode objects pass back a ++ pointer to the default encoded string version of the object if such a ++ conversion is possible. All other read-buffer compatible objects pass back ++ a reference to the raw internal data representation. ++ ++ Starting with Python 2.5 the type of the length argument can be controlled ++ by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before including ++ :file:`Python.h`. If the macro is defined, length is a :ctype:`Py_ssize_t` ++ rather than an int. ++ ++``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer] ++ Similar to ``s#``, this code fills a Py_buffer structure provided by the ++ caller. The buffer gets locked, so that the caller can subsequently use ++ the buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is ++ responsible for calling ``PyBuffer_Release`` with the structure after it ++ has processed the data. + + .. versionadded:: 2.6 + +-``z`` (string or ``None``) [const char \*] ++``z`` (string, Unicode or ``None``) [const char \*] + Like ``s``, but the Python object may also be ``None``, in which case the C + pointer is set to *NULL*. + +-``z#`` (string or ``None`` or any read buffer compatible object) [const char \*, int] ++``z#`` (string, Unicode, ``None`` or any read buffer compatible object) [const char \*, int] + This is to ``s#`` as ``z`` is to ``s``. + +-``z*`` (string or ``None`` or any buffer compatible object) [Py_buffer*] ++``z*`` (string, Unicode, ``None`` or any buffer compatible object) [Py_buffer] + This is to ``s*`` as ``z`` is to ``s``. + + .. versionadded:: 2.6 + +-``u`` (Unicode object) [Py_UNICODE \*] +- Convert a Python Unicode object to a C pointer to a NUL-terminated buffer of +- 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to provide +- storage for the Unicode data buffer; a pointer to the existing Unicode data is +- stored into the :ctype:`Py_UNICODE` pointer variable whose address you pass. +- +-``u#`` (Unicode object) [Py_UNICODE \*, int] +- This variant on ``u`` stores into two C variables, the first one a pointer to a +- Unicode data buffer, the second one its length. Non-Unicode objects are handled +- by interpreting their read-buffer pointer as pointer to a :ctype:`Py_UNICODE` +- array. +- +-``es`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer] +- This variant on ``s`` is used for encoding Unicode and objects convertible to +- Unicode into a character buffer. It only works for encoded data without embedded +- NUL bytes. ++``u`` (Unicode) [Py_UNICODE \*] ++ Convert a Python Unicode object to a C pointer to a NUL-terminated buffer ++ of 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to ++ provide storage for the Unicode data buffer; a pointer to the existing ++ Unicode data is stored into the :ctype:`Py_UNICODE` pointer variable whose ++ address you pass. ++ ++``u#`` (Unicode) [Py_UNICODE \*, int] ++ This variant on ``u`` stores into two C variables, the first one a pointer ++ to a Unicode data buffer, the second one its length. Non-Unicode objects ++ are handled by interpreting their read-buffer pointer as pointer to a ++ :ctype:`Py_UNICODE` array. ++ ++``es`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer] ++ This variant on ``s`` is used for encoding Unicode and objects convertible ++ to Unicode into a character buffer. It only works for encoded data without ++ embedded NUL bytes. + + This format requires two arguments. The first is only used as input, and +- must be a :ctype:`const char\*` which points to the name of an encoding as a +- NUL-terminated string, or *NULL*, in which case the default encoding is used. +- An exception is raised if the named encoding is not known to Python. The +- second argument must be a :ctype:`char\*\*`; the value of the pointer it +- references will be set to a buffer with the contents of the argument text. +- The text will be encoded in the encoding specified by the first argument. +- +- :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy the +- encoded data into this buffer and adjust *\*buffer* to reference the newly +- allocated storage. The caller is responsible for calling :cfunc:`PyMem_Free` to +- free the allocated buffer after use. ++ must be a :ctype:`const char\*` which points to the name of an encoding as ++ a NUL-terminated string, or *NULL*, in which case the default encoding is ++ used. An exception is raised if the named encoding is not known to Python. ++ The second argument must be a :ctype:`char\*\*`; the value of the pointer ++ it references will be set to a buffer with the contents of the argument ++ text. The text will be encoded in the encoding specified by the first ++ argument. ++ ++ :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy ++ the encoded data into this buffer and adjust *\*buffer* to reference the ++ newly allocated storage. The caller is responsible for calling ++ :cfunc:`PyMem_Free` to free the allocated buffer after use. + +-``et`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer] ++``et`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer] + Same as ``es`` except that 8-bit string objects are passed through without +- recoding them. Instead, the implementation assumes that the string object uses +- the encoding passed in as parameter. ++ recoding them. Instead, the implementation assumes that the string object ++ uses the encoding passed in as parameter. + +-``es#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length] +- This variant on ``s#`` is used for encoding Unicode and objects convertible to +- Unicode into a character buffer. Unlike the ``es`` format, this variant allows +- input data which contains NUL characters. +- +- It requires three arguments. The first is only used as input, and must be a +- :ctype:`const char\*` which points to the name of an encoding as a +- NUL-terminated string, or *NULL*, in which case the default encoding is used. +- An exception is raised if the named encoding is not known to Python. The +- second argument must be a :ctype:`char\*\*`; the value of the pointer it +- references will be set to a buffer with the contents of the argument text. +- The text will be encoded in the encoding specified by the first argument. +- The third argument must be a pointer to an integer; the referenced integer +- will be set to the number of bytes in the output buffer. ++``es#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length] ++ This variant on ``s#`` is used for encoding Unicode and objects convertible ++ to Unicode into a character buffer. Unlike the ``es`` format, this variant ++ allows input data which contains NUL characters. ++ ++ It requires three arguments. The first is only used as input, and must be ++ a :ctype:`const char\*` which points to the name of an encoding as a ++ NUL-terminated string, or *NULL*, in which case the default encoding is ++ used. An exception is raised if the named encoding is not known to Python. ++ The second argument must be a :ctype:`char\*\*`; the value of the pointer ++ it references will be set to a buffer with the contents of the argument ++ text. The text will be encoded in the encoding specified by the first ++ argument. The third argument must be a pointer to an integer; the ++ referenced integer will be set to the number of bytes in the output buffer. + + There are two modes of operation: + +- If *\*buffer* points a *NULL* pointer, the function will allocate a buffer of +- the needed size, copy the encoded data into this buffer and set *\*buffer* to +- reference the newly allocated storage. The caller is responsible for calling +- :cfunc:`PyMem_Free` to free the allocated buffer after usage. ++ If *\*buffer* points a *NULL* pointer, the function will allocate a buffer ++ of the needed size, copy the encoded data into this buffer and set ++ *\*buffer* to reference the newly allocated storage. The caller is ++ responsible for calling :cfunc:`PyMem_Free` to free the allocated buffer ++ after usage. + + If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer), +- :cfunc:`PyArg_ParseTuple` will use this location as the buffer and interpret the +- initial value of *\*buffer_length* as the buffer size. It will then copy the +- encoded data into the buffer and NUL-terminate it. If the buffer is not large +- enough, a :exc:`ValueError` will be set. ++ :cfunc:`PyArg_ParseTuple` will use this location as the buffer and ++ interpret the initial value of *\*buffer_length* as the buffer size. It ++ will then copy the encoded data into the buffer and NUL-terminate it. If ++ the buffer is not large enough, a :exc:`ValueError` will be set. + + In both cases, *\*buffer_length* is set to the length of the encoded data + without the trailing NUL byte. + +-``et#`` (string, Unicode object or character buffer compatible object) [const char \*encoding, char \*\*buffer] +- Same as ``es#`` except that string objects are passed through without recoding +- them. Instead, the implementation assumes that the string object uses the +- encoding passed in as parameter. ++``et#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length] ++ Same as ``es#`` except that string objects are passed through without ++ recoding them. Instead, the implementation assumes that the string object ++ uses the encoding passed in as parameter. + + ``b`` (integer) [unsigned char] + Convert a nonnegative Python integer to an unsigned tiny int, stored in a C + :ctype:`unsigned char`. + + ``B`` (integer) [unsigned char] +- Convert a Python integer to a tiny int without overflow checking, stored in a C +- :ctype:`unsigned char`. ++ Convert a Python integer to a tiny int without overflow checking, stored in ++ a C :ctype:`unsigned char`. + + .. versionadded:: 2.3 + + ``h`` (integer) [short int] + Convert a Python integer to a C :ctype:`short int`. + + ``H`` (integer) [unsigned short int] +- Convert a Python integer to a C :ctype:`unsigned short int`, without overflow +- checking. ++ Convert a Python integer to a C :ctype:`unsigned short int`, without ++ overflow checking. + + .. versionadded:: 2.3 + + ``i`` (integer) [int] + Convert a Python integer to a plain C :ctype:`int`. + + ``I`` (integer) [unsigned int] + Convert a Python integer to a C :ctype:`unsigned int`, without overflow + checking. + + .. versionadded:: 2.3 + + ``l`` (integer) [long int] + Convert a Python integer to a C :ctype:`long int`. + + ``k`` (integer) [unsigned long] +- Convert a Python integer or long integer to a C :ctype:`unsigned long` without +- overflow checking. ++ Convert a Python integer or long integer to a C :ctype:`unsigned long` ++ without overflow checking. + + .. versionadded:: 2.3 + + ``L`` (integer) [PY_LONG_LONG] + Convert a Python integer to a C :ctype:`long long`. This format is only +- available on platforms that support :ctype:`long long` (or :ctype:`_int64` on +- Windows). ++ available on platforms that support :ctype:`long long` (or :ctype:`_int64` ++ on Windows). + + ``K`` (integer) [unsigned PY_LONG_LONG] + Convert a Python integer or long integer to a C :ctype:`unsigned long long` + without overflow checking. This format is only available on platforms that +- support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on Windows). ++ support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on ++ Windows). + + .. versionadded:: 2.3 + + ``n`` (integer) [Py_ssize_t] + Convert a Python integer or long integer to a C :ctype:`Py_ssize_t`. + + .. versionadded:: 2.5 + + ``c`` (string of length 1) [char] + Convert a Python character, represented as a string of length 1, to a C + :ctype:`char`. + + ``f`` (float) [float] + Convert a Python floating point number to a C :ctype:`float`. + + ``d`` (float) [double] + Convert a Python floating point number to a C :ctype:`double`. + + ``D`` (complex) [Py_complex] + Convert a Python complex number to a C :ctype:`Py_complex` structure. + + ``O`` (object) [PyObject \*] +- Store a Python object (without any conversion) in a C object pointer. The C +- program thus receives the actual object that was passed. The object's reference +- count is not increased. The pointer stored is not *NULL*. ++ Store a Python object (without any conversion) in a C object pointer. The ++ C program thus receives the actual object that was passed. The object's ++ reference count is not increased. The pointer stored is not *NULL*. + + ``O!`` (object) [*typeobject*, PyObject \*] + Store a Python object in a C object pointer. This is similar to ``O``, but +- takes two C arguments: the first is the address of a Python type object, the +- second is the address of the C variable (of type :ctype:`PyObject\*`) into which +- the object pointer is stored. If the Python object does not have the required +- type, :exc:`TypeError` is raised. ++ takes two C arguments: the first is the address of a Python type object, ++ the second is the address of the C variable (of type :ctype:`PyObject\*`) ++ into which the object pointer is stored. If the Python object does not ++ have the required type, :exc:`TypeError` is raised. + + ``O&`` (object) [*converter*, *anything*] +- Convert a Python object to a C variable through a *converter* function. This +- takes two arguments: the first is a function, the second is the address of a C +- variable (of arbitrary type), converted to :ctype:`void \*`. The *converter* +- function in turn is called as follows:: ++ Convert a Python object to a C variable through a *converter* function. ++ This takes two arguments: the first is a function, the second is the ++ address of a C variable (of arbitrary type), converted to :ctype:`void \*`. ++ The *converter* function in turn is called as follows:: + + status = converter(object, address); + + where *object* is the Python object to be converted and *address* is the +- :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` function. +- The returned *status* should be ``1`` for a successful conversion and ``0`` if +- the conversion has failed. When the conversion fails, the *converter* function +- should raise an exception and leave the content of *address* unmodified. ++ :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*` ++ function. The returned *status* should be ``1`` for a successful ++ conversion and ``0`` if the conversion has failed. When the conversion ++ fails, the *converter* function should raise an exception and leave the ++ content of *address* unmodified. + + ``S`` (string) [PyStringObject \*] + Like ``O`` but requires that the Python object is a string object. Raises +- :exc:`TypeError` if the object is not a string object. The C variable may also +- be declared as :ctype:`PyObject\*`. ++ :exc:`TypeError` if the object is not a string object. The C variable may ++ also be declared as :ctype:`PyObject\*`. + + ``U`` (Unicode string) [PyUnicodeObject \*] + Like ``O`` but requires that the Python object is a Unicode object. Raises +- :exc:`TypeError` if the object is not a Unicode object. The C variable may also +- be declared as :ctype:`PyObject\*`. ++ :exc:`TypeError` if the object is not a Unicode object. The C variable may ++ also be declared as :ctype:`PyObject\*`. + + ``t#`` (read-only character buffer) [char \*, int] + Like ``s#``, but accepts any object which implements the read-only buffer +- interface. The :ctype:`char\*` variable is set to point to the first byte of +- the buffer, and the :ctype:`int` is set to the length of the buffer. Only +- single-segment buffer objects are accepted; :exc:`TypeError` is raised for all +- others. ++ interface. The :ctype:`char\*` variable is set to point to the first byte ++ of the buffer, and the :ctype:`int` is set to the length of the buffer. ++ Only single-segment buffer objects are accepted; :exc:`TypeError` is raised ++ for all others. + + ``w`` (read-write character buffer) [char \*] +- Similar to ``s``, but accepts any object which implements the read-write buffer +- interface. The caller must determine the length of the buffer by other means, +- or use ``w#`` instead. Only single-segment buffer objects are accepted; +- :exc:`TypeError` is raised for all others. ++ Similar to ``s``, but accepts any object which implements the read-write ++ buffer interface. The caller must determine the length of the buffer by ++ other means, or use ``w#`` instead. Only single-segment buffer objects are ++ accepted; :exc:`TypeError` is raised for all others. + + ``w#`` (read-write character buffer) [char \*, Py_ssize_t] + Like ``s#``, but accepts any object which implements the read-write buffer +- interface. The :ctype:`char \*` variable is set to point to the first byte of +- the buffer, and the :ctype:`int` is set to the length of the buffer. Only +- single-segment buffer objects are accepted; :exc:`TypeError` is raised for all +- others. ++ interface. The :ctype:`char \*` variable is set to point to the first byte ++ of the buffer, and the :ctype:`Py_ssize_t` is set to the length of the ++ buffer. Only single-segment buffer objects are accepted; :exc:`TypeError` ++ is raised for all others. + +-``w*`` (read-write byte-oriented buffer) [Py_buffer \*] ++``w*`` (read-write byte-oriented buffer) [Py_buffer] + This is to ``w`` what ``s*`` is to ``s``. + + .. versionadded:: 2.6 + + ``(items)`` (tuple) [*matching-items*] +- The object must be a Python sequence whose length is the number of format units +- in *items*. The C arguments must correspond to the individual format units in +- *items*. Format units for sequences may be nested. ++ The object must be a Python sequence whose length is the number of format ++ units in *items*. The C arguments must correspond to the individual format ++ units in *items*. Format units for sequences may be nested. + + .. note:: + +- Prior to Python version 1.5.2, this format specifier only accepted a tuple +- containing the individual parameters, not an arbitrary sequence. Code which +- previously caused :exc:`TypeError` to be raised here may now proceed without an +- exception. This is not expected to be a problem for existing code. ++ Prior to Python version 1.5.2, this format specifier only accepted a ++ tuple containing the individual parameters, not an arbitrary sequence. ++ Code which previously caused :exc:`TypeError` to be raised here may now ++ proceed without an exception. This is not expected to be a problem for ++ existing code. + + It is possible to pass Python long integers where integers are requested; + however no proper range checking is done --- the most significant bits are + silently truncated when the receiving field is too small to receive the value +-(actually, the semantics are inherited from downcasts in C --- your mileage may +-vary). ++(actually, the semantics are inherited from downcasts in C --- your mileage ++may vary). + + A few other characters have a meaning in a format string. These may not occur + inside nested parentheses. They are: + + ``|`` +- Indicates that the remaining arguments in the Python argument list are optional. +- The C variables corresponding to optional arguments should be initialized to +- their default value --- when an optional argument is not specified, +- :cfunc:`PyArg_ParseTuple` does not touch the contents of the corresponding C +- variable(s). ++ Indicates that the remaining arguments in the Python argument list are ++ optional. The C variables corresponding to optional arguments should be ++ initialized to their default value --- when an optional argument is not ++ specified, :cfunc:`PyArg_ParseTuple` does not touch the contents of the ++ corresponding C variable(s). + + ``:`` +- The list of format units ends here; the string after the colon is used as the +- function name in error messages (the "associated value" of the exception that +- :cfunc:`PyArg_ParseTuple` raises). ++ The list of format units ends here; the string after the colon is used as ++ the function name in error messages (the "associated value" of the ++ exception that :cfunc:`PyArg_ParseTuple` raises). + + ``;`` +- The list of format units ends here; the string after the semicolon is used as +- the error message *instead* of the default error message. ``:`` and ``;`` +- mutually exclude each other. ++ The list of format units ends here; the string after the semicolon is used ++ as the error message *instead* of the default error message. ``:`` and ++ ``;`` mutually exclude each other. + + Note that any Python object references which are provided to the caller are + *borrowed* references; do not decrement their reference count! + + Additional arguments passed to these functions must be addresses of variables + whose type is determined by the format string; these are used to store values +-from the input tuple. There are a few cases, as described in the list of format +-units above, where these parameters are used as input values; they should match +-what is specified for the corresponding format unit in that case. +- +-For the conversion to succeed, the *arg* object must match the format +-and the format must be exhausted. On success, the +-:cfunc:`PyArg_Parse\*` functions return true, otherwise they return +-false and raise an appropriate exception. When the +-:cfunc:`PyArg_Parse\*` functions fail due to conversion failure in one +-of the format units, the variables at the addresses corresponding to that ++from the input tuple. There are a few cases, as described in the list of ++format units above, where these parameters are used as input values; they ++should match what is specified for the corresponding format unit in that case. ++ ++For the conversion to succeed, the *arg* object must match the format and the ++format must be exhausted. On success, the :cfunc:`PyArg_Parse\*` functions ++return true, otherwise they return false and raise an appropriate exception. ++When the :cfunc:`PyArg_Parse\*` functions fail due to conversion failure in ++one of the format units, the variables at the addresses corresponding to that + and the following format units are left untouched. + + + .. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...) + +- Parse the parameters of a function that takes only positional parameters into +- local variables. Returns true on success; on failure, it returns false and +- raises the appropriate exception. ++ Parse the parameters of a function that takes only positional parameters ++ into local variables. Returns true on success; on failure, it returns ++ false and raises the appropriate exception. + + + .. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs) + +- Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list rather +- than a variable number of arguments. ++ Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list ++ rather than a variable number of arguments. + + + .. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...) + + Parse the parameters of a function that takes both positional and keyword + parameters into local variables. Returns true on success; on failure, it + returns false and raises the appropriate exception. + + + .. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs) + + Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a + va_list rather than a variable number of arguments. + + + .. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...) + +- Function used to deconstruct the argument lists of "old-style" functions --- +- these are functions which use the :const:`METH_OLDARGS` parameter parsing +- method. This is not recommended for use in parameter parsing in new code, and +- most code in the standard interpreter has been modified to no longer use this +- for that purpose. It does remain a convenient way to decompose other tuples, +- however, and may continue to be used for that purpose. ++ Function used to deconstruct the argument lists of "old-style" functions ++ --- these are functions which use the :const:`METH_OLDARGS` parameter ++ parsing method. This is not recommended for use in parameter parsing in ++ new code, and most code in the standard interpreter has been modified to no ++ longer use this for that purpose. It does remain a convenient way to ++ decompose other tuples, however, and may continue to be used for that ++ purpose. + + + .. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...) + + A simpler form of parameter retrieval which does not use a format string to +- specify the types of the arguments. Functions which use this method to retrieve +- their parameters should be declared as :const:`METH_VARARGS` in function or +- method tables. The tuple containing the actual parameters should be passed as +- *args*; it must actually be a tuple. The length of the tuple must be at least +- *min* and no more than *max*; *min* and *max* may be equal. Additional +- arguments must be passed to the function, each of which should be a pointer to a +- :ctype:`PyObject\*` variable; these will be filled in with the values from +- *args*; they will contain borrowed references. The variables which correspond +- to optional parameters not given by *args* will not be filled in; these should +- be initialized by the caller. This function returns true on success and false if +- *args* is not a tuple or contains the wrong number of elements; an exception +- will be set if there was a failure. ++ specify the types of the arguments. Functions which use this method to ++ retrieve their parameters should be declared as :const:`METH_VARARGS` in ++ function or method tables. The tuple containing the actual parameters ++ should be passed as *args*; it must actually be a tuple. The length of the ++ tuple must be at least *min* and no more than *max*; *min* and *max* may be ++ equal. Additional arguments must be passed to the function, each of which ++ should be a pointer to a :ctype:`PyObject\*` variable; these will be filled ++ in with the values from *args*; they will contain borrowed references. The ++ variables which correspond to optional parameters not given by *args* will ++ not be filled in; these should be initialized by the caller. This function ++ returns true on success and false if *args* is not a tuple or contains the ++ wrong number of elements; an exception will be set if there was a failure. + +- This is an example of the use of this function, taken from the sources for the +- :mod:`_weakref` helper module for weak references:: ++ This is an example of the use of this function, taken from the sources for ++ the :mod:`_weakref` helper module for weak references:: + + static PyObject * + weakref_ref(PyObject *self, PyObject *args) + { + PyObject *object; + PyObject *callback = NULL; + PyObject *result = NULL; + + if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) { + result = PyWeakref_NewRef(object, callback); + } + return result; + } + +- The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely equivalent to +- this call to :cfunc:`PyArg_ParseTuple`:: ++ The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely ++ equivalent to this call to :cfunc:`PyArg_ParseTuple`:: + + PyArg_ParseTuple(args, "O|O:ref", &object, &callback) + + .. versionadded:: 2.2 + ++ .. versionchanged:: 2.5 ++ This function used an :ctype:`int` type for *min* and *max*. This might ++ require changes in your code for properly supporting 64-bit systems. ++ + + .. cfunction:: PyObject* Py_BuildValue(const char *format, ...) + +- Create a new value based on a format string similar to those accepted by the +- :cfunc:`PyArg_Parse\*` family of functions and a sequence of values. Returns +- the value or *NULL* in the case of an error; an exception will be raised if +- *NULL* is returned. +- +- :cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple only if +- its format string contains two or more format units. If the format string is +- empty, it returns ``None``; if it contains exactly one format unit, it returns +- whatever object is described by that format unit. To force it to return a tuple +- of size 0 or one, parenthesize the format string. +- +- When memory buffers are passed as parameters to supply data to build objects, as +- for the ``s`` and ``s#`` formats, the required data is copied. Buffers provided +- by the caller are never referenced by the objects created by +- :cfunc:`Py_BuildValue`. In other words, if your code invokes :cfunc:`malloc` +- and passes the allocated memory to :cfunc:`Py_BuildValue`, your code is +- responsible for calling :cfunc:`free` for that memory once ++ Create a new value based on a format string similar to those accepted by ++ the :cfunc:`PyArg_Parse\*` family of functions and a sequence of values. ++ Returns the value or *NULL* in the case of an error; an exception will be ++ raised if *NULL* is returned. ++ ++ :cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple ++ only if its format string contains two or more format units. If the format ++ string is empty, it returns ``None``; if it contains exactly one format ++ unit, it returns whatever object is described by that format unit. To ++ force it to return a tuple of size 0 or one, parenthesize the format ++ string. ++ ++ When memory buffers are passed as parameters to supply data to build ++ objects, as for the ``s`` and ``s#`` formats, the required data is copied. ++ Buffers provided by the caller are never referenced by the objects created ++ by :cfunc:`Py_BuildValue`. In other words, if your code invokes ++ :cfunc:`malloc` and passes the allocated memory to :cfunc:`Py_BuildValue`, ++ your code is responsible for calling :cfunc:`free` for that memory once + :cfunc:`Py_BuildValue` returns. + +- In the following description, the quoted form is the format unit; the entry in +- (round) parentheses is the Python object type that the format unit will return; +- and the entry in [square] brackets is the type of the C value(s) to be passed. +- +- The characters space, tab, colon and comma are ignored in format strings (but +- not within format units such as ``s#``). This can be used to make long format +- strings a tad more readable. ++ In the following description, the quoted form is the format unit; the entry ++ in (round) parentheses is the Python object type that the format unit will ++ return; and the entry in [square] brackets is the type of the C value(s) to ++ be passed. ++ ++ The characters space, tab, colon and comma are ignored in format strings ++ (but not within format units such as ``s#``). This can be used to make ++ long format strings a tad more readable. + + ``s`` (string) [char \*] +- Convert a null-terminated C string to a Python object. If the C string pointer +- is *NULL*, ``None`` is used. ++ Convert a null-terminated C string to a Python object. If the C string ++ pointer is *NULL*, ``None`` is used. + + ``s#`` (string) [char \*, int] +- Convert a C string and its length to a Python object. If the C string pointer +- is *NULL*, the length is ignored and ``None`` is returned. ++ Convert a C string and its length to a Python object. If the C string ++ pointer is *NULL*, the length is ignored and ``None`` is returned. + + ``z`` (string or ``None``) [char \*] + Same as ``s``. + + ``z#`` (string or ``None``) [char \*, int] + Same as ``s#``. + + ``u`` (Unicode string) [Py_UNICODE \*] +- Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a Python +- Unicode object. If the Unicode buffer pointer is *NULL*, ``None`` is returned. ++ Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a ++ Python Unicode object. If the Unicode buffer pointer is *NULL*, ++ ``None`` is returned. + + ``u#`` (Unicode string) [Py_UNICODE \*, int] +- Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a Python +- Unicode object. If the Unicode buffer pointer is *NULL*, the length is ignored +- and ``None`` is returned. ++ Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a ++ Python Unicode object. If the Unicode buffer pointer is *NULL*, the ++ length is ignored and ``None`` is returned. + + ``i`` (integer) [int] + Convert a plain C :ctype:`int` to a Python integer object. + + ``b`` (integer) [char] + Convert a plain C :ctype:`char` to a Python integer object. + + ``h`` (integer) [short int] + Convert a plain C :ctype:`short int` to a Python integer object. + + ``l`` (integer) [long int] + Convert a C :ctype:`long int` to a Python integer object. + + ``B`` (integer) [unsigned char] + Convert a C :ctype:`unsigned char` to a Python integer object. + + ``H`` (integer) [unsigned short int] + Convert a C :ctype:`unsigned short int` to a Python integer object. + + ``I`` (integer/long) [unsigned int] +- Convert a C :ctype:`unsigned int` to a Python integer object or a Python long +- integer object, if it is larger than ``sys.maxint``. ++ Convert a C :ctype:`unsigned int` to a Python integer object or a Python ++ long integer object, if it is larger than ``sys.maxint``. + + ``k`` (integer/long) [unsigned long] +- Convert a C :ctype:`unsigned long` to a Python integer object or a Python long +- integer object, if it is larger than ``sys.maxint``. ++ Convert a C :ctype:`unsigned long` to a Python integer object or a ++ Python long integer object, if it is larger than ``sys.maxint``. + + ``L`` (long) [PY_LONG_LONG] +- Convert a C :ctype:`long long` to a Python long integer object. Only available +- on platforms that support :ctype:`long long`. ++ Convert a C :ctype:`long long` to a Python long integer object. Only ++ available on platforms that support :ctype:`long long`. + + ``K`` (long) [unsigned PY_LONG_LONG] +- Convert a C :ctype:`unsigned long long` to a Python long integer object. Only +- available on platforms that support :ctype:`unsigned long long`. ++ Convert a C :ctype:`unsigned long long` to a Python long integer object. ++ Only available on platforms that support :ctype:`unsigned long long`. + + ``n`` (int) [Py_ssize_t] + Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer. + + .. versionadded:: 2.5 + + ``c`` (string of length 1) [char] +- Convert a C :ctype:`int` representing a character to a Python string of length +- 1. ++ Convert a C :ctype:`int` representing a character to a Python string of ++ length 1. + + ``d`` (float) [double] + Convert a C :ctype:`double` to a Python floating point number. + + ``f`` (float) [float] + Same as ``d``. + + ``D`` (complex) [Py_complex \*] + Convert a C :ctype:`Py_complex` structure to a Python complex number. + + ``O`` (object) [PyObject \*] + Pass a Python object untouched (except for its reference count, which is +- incremented by one). If the object passed in is a *NULL* pointer, it is assumed +- that this was caused because the call producing the argument found an error and +- set an exception. Therefore, :cfunc:`Py_BuildValue` will return *NULL* but won't +- raise an exception. If no exception has been raised yet, :exc:`SystemError` is +- set. ++ incremented by one). If the object passed in is a *NULL* pointer, it is ++ assumed that this was caused because the call producing the argument ++ found an error and set an exception. Therefore, :cfunc:`Py_BuildValue` ++ will return *NULL* but won't raise an exception. If no exception has ++ been raised yet, :exc:`SystemError` is set. + + ``S`` (object) [PyObject \*] + Same as ``O``. + + ``N`` (object) [PyObject \*] +- Same as ``O``, except it doesn't increment the reference count on the object. +- Useful when the object is created by a call to an object constructor in the +- argument list. ++ Same as ``O``, except it doesn't increment the reference count on the ++ object. Useful when the object is created by a call to an object ++ constructor in the argument list. + + ``O&`` (object) [*converter*, *anything*] +- Convert *anything* to a Python object through a *converter* function. The +- function is called with *anything* (which should be compatible with :ctype:`void +- \*`) as its argument and should return a "new" Python object, or *NULL* if an +- error occurred. ++ Convert *anything* to a Python object through a *converter* function. ++ The function is called with *anything* (which should be compatible with ++ :ctype:`void \*`) as its argument and should return a "new" Python ++ object, or *NULL* if an error occurred. + + ``(items)`` (tuple) [*matching-items*] +- Convert a sequence of C values to a Python tuple with the same number of items. ++ Convert a sequence of C values to a Python tuple with the same number of ++ items. + + ``[items]`` (list) [*matching-items*] +- Convert a sequence of C values to a Python list with the same number of items. ++ Convert a sequence of C values to a Python list with the same number of ++ items. + + ``{items}`` (dictionary) [*matching-items*] +- Convert a sequence of C values to a Python dictionary. Each pair of consecutive +- C values adds one item to the dictionary, serving as key and value, +- respectively. ++ Convert a sequence of C values to a Python dictionary. Each pair of ++ consecutive C values adds one item to the dictionary, serving as key and ++ value, respectively. + +- If there is an error in the format string, the :exc:`SystemError` exception is +- set and *NULL* returned. ++ If there is an error in the format string, the :exc:`SystemError` exception ++ is set and *NULL* returned. + + .. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs) + + Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list + rather than a variable number of arguments. ======================================= --- /dev/null +++ /c-api/diff/arg.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,559 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to3__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/arg.rst => r266/c-api/arg.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to3__0"></td><td class="diff_header" id="from3_5">5</td><td nowrap="nowrap">Parsing arguments and building values</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_6">6</td><td nowrap="nowrap">=====================================</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_7">7</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_8">8</td><td nowrap="nowrap">These functions are useful when creating your own extensions functions and</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_9">9</td><td nowrap="nowrap">methods. Additional information and examples are available in</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_10">10</td><td nowrap="nowrap">:ref:`extending-index`.</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__1"></td><td class="diff_header" id="from3_11">11</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_12">12</td><td nowrap="nowrap">The first three of these functions described, :cfunc:`PyArg_ParseTuple`,</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__1">n</a></td><td class="diff_header" id="from3_13">13-</td><td nowrap="nowrap">:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use<span class="diff_sub"> *format</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__1">n</a></td><td class="diff_header" id="to3_13">13+</td><td nowrap="nowrap">:cfunc:`PyArg_ParseTupleAndKeywords`, and :cfunc:`PyArg_Parse`, all use</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_14">14-</td><td nowrap="nowrap">strings* which are used to tell the function about the expected<span class="diff_sub"> arguments. The</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_14">14+</td><td nowrap="nowrap"><span class="diff_add">*format </span>strings* which are used to tell the function about the expected</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_15">15-</td><td nowrap="nowrap">format strings use the same syntax for each of these<span class="diff_sub"> functions.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_15">15+</td><td nowrap="nowrap"><span class="diff_add">arguments. The </span>format strings use the same syntax for each of these</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_16">16+</td><td nowrap="nowrap"><span class="diff_add">functions.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_16">16</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_17">17</td><td nowrap="nowrap">A format string consists of zero or more "format units." A format unit</td></tr><tr><td class="diff_next" id="difflib_chg_to3__2"><a href="#difflib_chg_to3__2">n</a></td><td class="diff_header" id="from3_18">18-</td><td nowrap="nowrap">describes one Python object; it is usually a single character or a<span class="diff_sub"> parenthesized</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__2"><a href="#difflib_chg_to3__2">n</a></td><td class="diff_header" id="to3_19">19+</td><td nowrap="nowrap">describes one Python object; it is usually a single character or a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_19">19-</td><td nowrap="nowrap">sequence of format units. With a few exceptions, a format unit<span class="diff_sub"> that is not a</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_20">20+</td><td nowrap="nowrap"><span class="diff_add">parenthesized </span>sequence of format units. With a few exceptions, a format unit</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_20">20-</td><td nowrap="nowrap">parenthesized sequence normally corresponds to a single address<span class="diff_sub"> argument to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_21">21+</td><td nowrap="nowrap"><span class="diff_add">that is not a </span>parenthesized sequence normally corresponds to a single address</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_21">21-</td><td nowrap="nowrap">these functions. In the following description, the quoted form is<span class="diff_sub"> the format</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_22">22+</td><td nowrap="nowrap"><span class="diff_add">argument to </span>these functions. In the following description, the quoted form is</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_22">22-</td><td nowrap="nowrap">unit; the entry in (round) parentheses is the Python object type<span class="diff_sub"> that matches</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_23">23+</td><td nowrap="nowrap"><span class="diff_add">the format </span>unit; the entry in (round) parentheses is the Python object type</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_23">23-</td><td nowrap="nowrap">the format unit; and the entry in [square] brackets is the type<span class="diff_sub"> of the C</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_24">24+</td><td nowrap="nowrap"><span class="diff_add">that matches </span>the format unit; and the entry in [square] brackets is the type</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_24">24-</td><td nowrap="nowrap">variable(s) whose address should be passed.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_25">25+</td><td nowrap="nowrap"><span class="diff_add">of the C </span>variable(s) whose address should be passed.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_25">25</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__3">n</a></td><td class="diff_header" id="from3_26">26-</td><td nowrap="nowrap">``s`` (string or Unicode<span class="diff_sub"> object</span>) [const char \*]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__3">n</a></td><td class="diff_header" id="to3_27">27+</td><td nowrap="nowrap">``s`` (string or Unicode) [const char \*]</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_27">27-</td><td nowrap="nowrap"> Convert a Python string or Unicode object to a C pointer to a character<span class="diff_sub"> string.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_28">28+</td><td nowrap="nowrap"> Convert a Python string or Unicode object to a C pointer to a character</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__3"></td><td class="diff_header" id="from3_28">28-</td><td nowrap="nowrap"> You must not provide storage for the string itself; a pointer to<span class="diff_sub"> an existing</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__3"></td><td class="diff_header" id="to3_29">29+</td><td nowrap="nowrap"> <span class="diff_add"> string.</span> You must not provide storage for the string itself; a pointer to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_29">29-</td><td nowrap="nowrap"> string is stored into the character pointer variable whose<span class="diff_sub"> address you pass.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_30">30+</td><td nowrap="nowrap"> <span class="diff_add"> an existing</span> string is stored into the character pointer variable whose</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_30">30-</td><td nowrap="nowrap"><span class="diff_sub"> The C string is NUL-terminated. The Python string must not contain embedded NUL</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_31">31+</td><td nowrap="nowrap"><span class="diff_add"> address you pass. The C string is NUL-terminated. The Python string must</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_31">31-</td><td nowrap="nowrap"><span class="diff_sub"> bytes; if it does, a :exc:`TypeError` exception is raised. Unicode objects are</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_32">32+</td><td nowrap="nowrap"><span class="diff_add"> not contain embedded NUL bytes; if it does, a :exc:`TypeError` exception is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_32">32-</td><td nowrap="nowrap"><span class="diff_sub"> converted to C strings using the default encoding. If this conversion fails, a</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_33">33+</td><td nowrap="nowrap"><span class="diff_add"> raised. Unicode objects are converted to C strings using the default</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_33">33-</td><td nowrap="nowrap"><span class="diff_sub"> :exc:`UnicodeError` is raised.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_34">34+</td><td nowrap="nowrap"><span class="diff_add"> encoding. If this conversion fails, a :exc:`UnicodeError` is raised.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_34">34</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to3__4"></td><td class="diff_header" id="from3_35">35</td><td nowrap="nowrap">``s#`` (string, Unicode or any read buffer compatible object) [const char \*, int (or :ctype:`Py_ssize_t`, see below)]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__4">n</a></td><td class="diff_header" id="from3_36">36-</td><td nowrap="nowrap"> This variant on ``s`` stores into two C variables, the first one a pointer<span class="diff_sub"> to a</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__4">n</a></td><td class="diff_header" id="to3_37">37+</td><td nowrap="nowrap"> This variant on ``s`` stores into two C variables, the first one a pointer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_37">37-</td><td nowrap="nowrap"> character string, the second one its length. In this case the Python<span class="diff_sub"> string may</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_38">38+</td><td nowrap="nowrap"> <span class="diff_add"> to a</span> character string, the second one its length. In this case the Python</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_38">38-</td><td nowrap="nowrap"> contain embedded null bytes. Unicode objects pass back a<span class="diff_sub"> pointer to the default</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_39">39+</td><td nowrap="nowrap"> <span class="diff_add"> string may</span> contain embedded null bytes. Unicode objects pass back a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_39">39-</td><td nowrap="nowrap"><span class="diff_sub"> encoded string version of the object if such a conversion is possible. All</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_40">40+</td><td nowrap="nowrap"><span class="diff_add"> pointer to the default encoded string version of the object if such a</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__5"></td><td class="diff_header" id="from3_40">40-</td><td nowrap="nowrap"><span class="diff_sub"> other read-buffer compatible objects pass back a reference to the raw internal</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__5"></td><td class="diff_header" id="to3_41">41+</td><td nowrap="nowrap"><span class="diff_add"> conversion is possible. All other read-buffer compatible objects pass back</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_41">41-</td><td nowrap="nowrap"><span class="diff_sub"> data representation.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_42">42+</td><td nowrap="nowrap"><span class="diff_add"> a reference to the raw internal data representation.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_42">42</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__5">n</a></td><td class="diff_header" id="from3_43">43-</td><td nowrap="nowrap"> Starting with Python 2.5 the type of the length argument can be</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__5">n</a></td><td class="diff_header" id="to3_44">44+</td><td nowrap="nowrap"> Starting with Python 2.5 the type of the length argument can be<span class="diff_add"> controlled</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_44">44-</td><td nowrap="nowrap"> <span class="diff_sub"> controlled</span> by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_45">45+</td><td nowrap="nowrap"> by defining the macro :cmacro:`PY_SSIZE_T_CLEAN` before<span class="diff_add"> including</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_45">45-</td><td nowrap="nowrap"> <span class="diff_sub"> including</span> :file:`Python.h`. If the macro is defined, length is a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_46">46+</td><td nowrap="nowrap"> :file:`Python.h`. If the macro is defined, length is a<span class="diff_add"> :ctype:`Py_ssize_t`</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_46">46-</td><td nowrap="nowrap"><span class="diff_sub"> :ctype:`Py_ssize_t` rather than an int.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_47">47+</td><td nowrap="nowrap"><span class="diff_add"> rather than an int.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_47">47</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__6">n</a></td><td class="diff_header" id="from3_48">48-</td><td nowrap="nowrap">``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer<span class="diff_sub"> \*</span>]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__6">n</a></td><td class="diff_header" id="to3_49">49+</td><td nowrap="nowrap">``s*`` (string, Unicode, or any buffer compatible object) [Py_buffer]</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__6"></td><td class="diff_header" id="from3_49">49-</td><td nowrap="nowrap"> Similar to ``s#``, this code fills a Py_buffer structure provided by the<span class="diff_sub"> caller.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__6"></td><td class="diff_header" id="to3_50">50+</td><td nowrap="nowrap"> Similar to ``s#``, this code fills a Py_buffer structure provided by the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_50">50-</td><td nowrap="nowrap"> The buffer gets locked, so that the caller can subsequently use<span class="diff_sub"> the buffer even</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_51">51+</td><td nowrap="nowrap"> <span class="diff_add"> caller.</span> The buffer gets locked, so that the caller can subsequently use</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_51">51-</td><td nowrap="nowrap"><span class="diff_sub"> inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is responsible for calling</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_52">52+</td><td nowrap="nowrap"><span class="diff_add"> the buffer even inside a ``Py_BEGIN_ALLOW_THREADS`` block; the caller is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_52">52-</td><td nowrap="nowrap"><span class="diff_sub"> ``PyBuffer_Release`` with the structure after it has processed the data.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_53">53+</td><td nowrap="nowrap"><span class="diff_add"> responsible for calling ``PyBuffer_Release`` with the structure after it</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__7"></td><td class="diff_header" id="to3_54">54+</td><td nowrap="nowrap"><span class="diff_add"> has processed the data.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_53">53</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_54">54</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__8"></td><td class="diff_header" id="from3_55">55</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__7">n</a></td><td class="diff_header" id="from3_56">56-</td><td nowrap="nowrap">``z`` (string or ``None``) [const char \*]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__7">n</a></td><td class="diff_header" id="to3_58">58+</td><td nowrap="nowrap">``z`` (string<span class="diff_add">, Unicode </span> or ``None``) [const char \*]</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_57">57</td><td nowrap="nowrap"> Like ``s``, but the Python object may also be ``None``, in which case the C</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_58">58</td><td nowrap="nowrap"> pointer is set to *NULL*.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_59">59</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next" id="difflib_chg_to3__9"><a href="#difflib_chg_to3__8">n</a></td><td class="diff_header" id="from3_60">60-</td><td nowrap="nowrap">``z#`` (string<span class="diff_chg"> </span>o<span class="diff_chg">r</span> ``None`` or any read buffer compatible object) [const char \*, int]</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__9"><a href="#difflib_chg_to3__8">n</a></td><td class="diff_header" id="to3_62">62+</td><td nowrap="nowrap">``z#`` (string<span class="diff_chg">, Unic</span>o<span class="diff_chg">de,</span> ``None`` or any read buffer compatible object) [const char \*, int]</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_61">61</td><td nowrap="nowrap"> This is to ``s#`` as ``z`` is to ``s``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_62">62</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__9">n</a></td><td class="diff_header" id="from3_63">63-</td><td nowrap="nowrap">``z*`` (string<span class="diff_chg"> </span>o<span class="diff_chg">r</span> ``None`` or any buffer compatible object) [Py_buffer<span class="diff_sub">*</span>]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__9">n</a></td><td class="diff_header" id="to3_65">65+</td><td nowrap="nowrap">``z*`` (string<span class="diff_chg">, Unic</span>o<span class="diff_chg">de,</span> ``None`` or any buffer compatible object) [Py_buffer]</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_64">64</td><td nowrap="nowrap"> This is to ``s*`` as ``z`` is to ``s``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_65">65</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_66">66</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__10"></td><td class="diff_header" id="from3_67">67</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__10">n</a></td><td class="diff_header" id="from3_68">68-</td><td nowrap="nowrap">``u`` (Unicode<span class="diff_sub"> object</span>) [Py_UNICODE \*]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__10">n</a></td><td class="diff_header" id="to3_70">70+</td><td nowrap="nowrap">``u`` (Unicode) [Py_UNICODE \*]</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_69">69-</td><td nowrap="nowrap"> Convert a Python Unicode object to a C pointer to a NUL-terminated buffer<span class="diff_sub"> of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_71">71+</td><td nowrap="nowrap"> Convert a Python Unicode object to a C pointer to a NUL-terminated buffer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_70">70-</td><td nowrap="nowrap"> 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to<span class="diff_sub"> provide</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_72">72+</td><td nowrap="nowrap"> <span class="diff_add"> of</span> 16-bit Unicode (UTF-16) data. As with ``s``, there is no need to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_71">71-</td><td nowrap="nowrap"> storage for the Unicode data buffer; a pointer to the existing<span class="diff_sub"> Unicode data is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_73">73+</td><td nowrap="nowrap"> <span class="diff_add"> provide</span> storage for the Unicode data buffer; a pointer to the existing</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_72">72-</td><td nowrap="nowrap"> stored into the :ctype:`Py_UNICODE` pointer variable whose<span class="diff_sub"> address you pass.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_74">74+</td><td nowrap="nowrap"> <span class="diff_add"> Unicode data is</span> stored into the :ctype:`Py_UNICODE` pointer variable whose</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__11"></td><td class="diff_header" id="to3_75">75+</td><td nowrap="nowrap"><span class="diff_add"> address you pass.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_73">73</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__11">n</a></td><td class="diff_header" id="from3_74">74-</td><td nowrap="nowrap">``u#`` (Unicode<span class="diff_sub"> object</span>) [Py_UNICODE \*, int]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__11">n</a></td><td class="diff_header" id="to3_77">77+</td><td nowrap="nowrap">``u#`` (Unicode) [Py_UNICODE \*, int]</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_75">75-</td><td nowrap="nowrap"> This variant on ``u`` stores into two C variables, the first one a pointer<span class="diff_sub"> to a</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_78">78+</td><td nowrap="nowrap"> This variant on ``u`` stores into two C variables, the first one a pointer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_76">76-</td><td nowrap="nowrap"> Unicode data buffer, the second one its length. Non-Unicode objects<span class="diff_sub"> are handled</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_79">79+</td><td nowrap="nowrap"> <span class="diff_add"> to a</span> Unicode data buffer, the second one its length. Non-Unicode objects</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_77">77-</td><td nowrap="nowrap"> by interpreting their read-buffer pointer as pointer to a<span class="diff_sub"> :ctype:`Py_UNICODE`</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_80">80+</td><td nowrap="nowrap"> <span class="diff_add"> are handled</span> by interpreting their read-buffer pointer as pointer to a</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__12"></td><td class="diff_header" id="from3_78">78-</td><td nowrap="nowrap"><span class="diff_sub"> array.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__12"></td><td class="diff_header" id="to3_81">81+</td><td nowrap="nowrap"><span class="diff_add"> :ctype:`Py_UNICODE` array.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_79">79</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__12">n</a></td><td class="diff_header" id="from3_80">80-</td><td nowrap="nowrap">``es`` (string, Unicode <span class="diff_sub">object </span>or character buffer compatible object) [const char \*encoding, char \*\*buffer]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__12">n</a></td><td class="diff_header" id="to3_83">83+</td><td nowrap="nowrap">``es`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_81">81-</td><td nowrap="nowrap"> This variant on ``s`` is used for encoding Unicode and objects convertible<span class="diff_sub"> to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_84">84+</td><td nowrap="nowrap"> This variant on ``s`` is used for encoding Unicode and objects convertible</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_82">82-</td><td nowrap="nowrap"> Unicode into a character buffer. It only works for encoded data without<span class="diff_sub"> embedded</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_85">85+</td><td nowrap="nowrap"> <span class="diff_add"> to</span> Unicode into a character buffer. It only works for encoded data without</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_83">83-</td><td nowrap="nowrap"><span class="diff_sub"> NUL bytes.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_86">86+</td><td nowrap="nowrap"><span class="diff_add"> embedded NUL bytes.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_84">84</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_85">85</td><td nowrap="nowrap"> This format requires two arguments. The first is only used as input, and</td></tr><tr><td class="diff_next" id="difflib_chg_to3__13"><a href="#difflib_chg_to3__13">n</a></td><td class="diff_header" id="from3_86">86-</td><td nowrap="nowrap"> must be a :ctype:`const char\*` which points to the name of an encoding as<span class="diff_sub"> a</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__13"><a href="#difflib_chg_to3__13">n</a></td><td class="diff_header" id="to3_89">89+</td><td nowrap="nowrap"> must be a :ctype:`const char\*` which points to the name of an encoding as</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_87">87-</td><td nowrap="nowrap"> NUL-terminated string, or *NULL*, in which case the default encoding is<span class="diff_sub"> used.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_90">90+</td><td nowrap="nowrap"> <span class="diff_add"> a</span> NUL-terminated string, or *NULL*, in which case the default encoding is</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_88">88-</td><td nowrap="nowrap"> An exception is raised if the named encoding is not known to Python.<span class="diff_sub"> The</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_91">91+</td><td nowrap="nowrap"> <span class="diff_add"> used.</span> An exception is raised if the named encoding is not known to Python.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_89">89-</td><td nowrap="nowrap"> second argument must be a :ctype:`char\*\*`; the value of the pointer<span class="diff_sub"> it</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_92">92+</td><td nowrap="nowrap"> <span class="diff_add"> The</span> second argument must be a :ctype:`char\*\*`; the value of the pointer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_90">90-</td><td nowrap="nowrap"> references will be set to a buffer with the contents of the argument<span class="diff_sub"> text.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_93">93+</td><td nowrap="nowrap"> <span class="diff_add"> it</span> references will be set to a buffer with the contents of the argument</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__14"></td><td class="diff_header" id="from3_91">91-</td><td nowrap="nowrap"> <span class="diff_sub"> The</span> text will be encoded in the encoding specified by the first<span class="diff_sub"> argument.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__14"></td><td class="diff_header" id="to3_94">94+</td><td nowrap="nowrap"> text<span class="diff_add">. The text</span> will be encoded in the encoding specified by the first</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_95">95+</td><td nowrap="nowrap"><span class="diff_add"> argument.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to3__15"></td><td class="diff_header" id="from3_92">92</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__14">n</a></td><td class="diff_header" id="from3_93">93-</td><td nowrap="nowrap"> :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__14">n</a></td><td class="diff_header" id="to3_97">97+</td><td nowrap="nowrap"> :cfunc:`PyArg_ParseTuple` will allocate a buffer of the needed size, copy</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_94">94-</td><td nowrap="nowrap"> encoded data into this buffer and adjust *\*buffer* to reference the<span class="diff_sub"> newly</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_98">98+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> encoded data into this buffer and adjust *\*buffer* to reference the</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__16"></td><td class="diff_header" id="from3_95">95-</td><td nowrap="nowrap"> allocated storage. The caller is responsible for calling<span class="diff_sub"> :cfunc:`PyMem_Free` to</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__16"></td><td class="diff_header" id="to3_99">99+</td><td nowrap="nowrap"> <span class="diff_add"> newly</span> allocated storage. The caller is responsible for calling</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_96">96-</td><td nowrap="nowrap"> free the allocated buffer after use.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_100">100+</td><td nowrap="nowrap"> <span class="diff_add"> :cfunc:`PyMem_Free` to</span> free the allocated buffer after use.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_97">97</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__15">n</a></td><td class="diff_header" id="from3_98">98-</td><td nowrap="nowrap">``et`` (string, Unicode <span class="diff_sub">object </span>or character buffer compatible object) [const char \*encoding, char \*\*buffer]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__15">n</a></td><td class="diff_header" id="to3_102">102+</td><td nowrap="nowrap">``et`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer]</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_99">99</td><td nowrap="nowrap"> Same as ``es`` except that 8-bit string objects are passed through without</td></tr><tr><td class="diff_next" id="difflib_chg_to3__17"><a href="#difflib_chg_to3__16">n</a></td><td class="diff_header" id="from3_100">100-</td><td nowrap="nowrap"> recoding them. Instead, the implementation assumes that the string object<span class="diff_sub"> uses</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__17"><a href="#difflib_chg_to3__16">n</a></td><td class="diff_header" id="to3_104">104+</td><td nowrap="nowrap"> recoding them. Instead, the implementation assumes that the string object</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_101">101-</td><td nowrap="nowrap"> the encoding passed in as parameter.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_105">105+</td><td nowrap="nowrap"> <span class="diff_add"> uses</span> the encoding passed in as parameter.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_102">102</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__17">n</a></td><td class="diff_header" id="from3_103">103-</td><td nowrap="nowrap">``es#`` (string, Unicode <span class="diff_sub">object </span>or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__17">n</a></td><td class="diff_header" id="to3_107">107+</td><td nowrap="nowrap">``es#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer, int \*buffer_length]</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_104">104-</td><td nowrap="nowrap"> This variant on ``s#`` is used for encoding Unicode and objects convertible<span class="diff_sub"> to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_108">108+</td><td nowrap="nowrap"> This variant on ``s#`` is used for encoding Unicode and objects convertible</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_105">105-</td><td nowrap="nowrap"> Unicode into a character buffer. Unlike the ``es`` format, this variant<span class="diff_sub"> allows</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_109">109+</td><td nowrap="nowrap"> <span class="diff_add"> to</span> Unicode into a character buffer. Unlike the ``es`` format, this variant</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_106">106-</td><td nowrap="nowrap"> input data which contains NUL characters.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_110">110+</td><td nowrap="nowrap"> <span class="diff_add"> allows</span> input data which contains NUL characters.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_107">107</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__18">n</a></td><td class="diff_header" id="from3_108">108-</td><td nowrap="nowrap"> It requires three arguments. The first is only used as input, and must be<span class="diff_sub"> a</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__18">n</a></td><td class="diff_header" id="to3_112">112+</td><td nowrap="nowrap"> It requires three arguments. The first is only used as input, and must be</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_109">109-</td><td nowrap="nowrap"> :ctype:`const char\*` which points to the name of an encoding as a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_113">113+</td><td nowrap="nowrap"> <span class="diff_add"> a</span> :ctype:`const char\*` which points to the name of an encoding as a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_110">110-</td><td nowrap="nowrap"> NUL-terminated string, or *NULL*, in which case the default encoding is<span class="diff_sub"> used.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_114">114+</td><td nowrap="nowrap"> NUL-terminated string, or *NULL*, in which case the default encoding is</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_111">111-</td><td nowrap="nowrap"> An exception is raised if the named encoding is not known to Python.<span class="diff_sub"> The</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_115">115+</td><td nowrap="nowrap"> <span class="diff_add"> used.</span> An exception is raised if the named encoding is not known to Python.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__18"></td><td class="diff_header" id="from3_112">112-</td><td nowrap="nowrap"> second argument must be a :ctype:`char\*\*`; the value of the pointer<span class="diff_sub"> it</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__18"></td><td class="diff_header" id="to3_116">116+</td><td nowrap="nowrap"> <span class="diff_add"> The</span> second argument must be a :ctype:`char\*\*`; the value of the pointer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_113">113-</td><td nowrap="nowrap"> references will be set to a buffer with the contents of the argument<span class="diff_sub"> text.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_117">117+</td><td nowrap="nowrap"> <span class="diff_add"> it</span> references will be set to a buffer with the contents of the argument</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_114">114-</td><td nowrap="nowrap"> <span class="diff_sub"> The</span> text will be encoded in the encoding specified by the first<span class="diff_sub"> argument.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_118">118+</td><td nowrap="nowrap"> text<span class="diff_add">. The text</span> will be encoded in the encoding specified by the first</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_115">115-</td><td nowrap="nowrap"><span class="diff_sub"> The third argument must be a pointer to an integer; the referenced integer</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_119">119+</td><td nowrap="nowrap"><span class="diff_add"> argument. The third argument must be a pointer to an integer; the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_116">116-</td><td nowrap="nowrap"> will be set to the number of bytes in the output buffer.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_120">120+</td><td nowrap="nowrap"> <span class="diff_add"> referenced integer</span> will be set to the number of bytes in the output buffer.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_117">117</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_118">118</td><td nowrap="nowrap"> There are two modes of operation:</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__19"></td><td class="diff_header" id="from3_119">119</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__19">n</a></td><td class="diff_header" id="from3_120">120-</td><td nowrap="nowrap"> If *\*buffer* points a *NULL* pointer, the function will allocate a buffer<span class="diff_sub"> of</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__19">n</a></td><td class="diff_header" id="to3_124">124+</td><td nowrap="nowrap"> If *\*buffer* points a *NULL* pointer, the function will allocate a buffer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_121">121-</td><td nowrap="nowrap"> the needed size, copy the encoded data into this buffer and set<span class="diff_sub"> *\*buffer* to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_125">125+</td><td nowrap="nowrap"> <span class="diff_add"> of</span> the needed size, copy the encoded data into this buffer and set</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_122">122-</td><td nowrap="nowrap"><span class="diff_sub"> reference the newly allocated storage. The caller is responsible for calling</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_126">126+</td><td nowrap="nowrap"><span class="diff_add"> *\*buffer* to reference the newly allocated storage. The caller is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_123">123-</td><td nowrap="nowrap"><span class="diff_sub"> :cfunc:`PyMem_Free` to free the allocated buffer after usage.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_127">127+</td><td nowrap="nowrap"><span class="diff_add"> responsible for calling :cfunc:`PyMem_Free` to free the allocated buffer</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_128">128+</td><td nowrap="nowrap"><span class="diff_add"> after usage.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_124">124</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_125">125</td><td nowrap="nowrap"> If *\*buffer* points to a non-*NULL* pointer (an already allocated buffer),</td></tr><tr><td class="diff_next" id="difflib_chg_to3__20"><a href="#difflib_chg_to3__20">n</a></td><td class="diff_header" id="from3_126">126-</td><td nowrap="nowrap"> :cfunc:`PyArg_ParseTuple` will use this location as the buffer and<span class="diff_sub"> interpret the</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__20"><a href="#difflib_chg_to3__20">n</a></td><td class="diff_header" id="to3_131">131+</td><td nowrap="nowrap"> :cfunc:`PyArg_ParseTuple` will use this location as the buffer and</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_127">127-</td><td nowrap="nowrap"> initial value of *\*buffer_length* as the buffer size. It<span class="diff_sub"> will then copy the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_132">132+</td><td nowrap="nowrap"> <span class="diff_add"> interpret the</span> initial value of *\*buffer_length* as the buffer size. It</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_128">128-</td><td nowrap="nowrap"><span class="diff_sub"> encoded data into the buffer and NUL-terminate it. If the buffer is not large</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_133">133+</td><td nowrap="nowrap"><span class="diff_add"> will then copy the encoded data into the buffer and NUL-terminate it. If</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_129">129-</td><td nowrap="nowrap"> enough, a :exc:`ValueError` will be set.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_134">134+</td><td nowrap="nowrap"> <span class="diff_add"> the buffer is not large</span> enough, a :exc:`ValueError` will be set.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_130">130</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_131">131</td><td nowrap="nowrap"> In both cases, *\*buffer_length* is set to the length of the encoded data</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_132">132</td><td nowrap="nowrap"> without the trailing NUL byte.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_133">133</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__21">n</a></td><td class="diff_header" id="from3_134">134-</td><td nowrap="nowrap">``et#`` (string, Unicode <span class="diff_sub">object </span>or character buffer compatible object) [const char \*encoding, char \*\*buffer]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__21">n</a></td><td class="diff_header" id="to3_139">139+</td><td nowrap="nowrap">``et#`` (string, Unicode or character buffer compatible object) [const char \*encoding, char \*\*buffer<span class="diff_add">, int \*buffer_length</span>]</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_135">135-</td><td nowrap="nowrap"> Same as ``es#`` except that string objects are passed through without<span class="diff_sub"> recoding</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_140">140+</td><td nowrap="nowrap"> Same as ``es#`` except that string objects are passed through without</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__21"></td><td class="diff_header" id="from3_136">136-</td><td nowrap="nowrap"> them. Instead, the implementation assumes that the string object<span class="diff_sub"> uses the</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__21"></td><td class="diff_header" id="to3_141">141+</td><td nowrap="nowrap"> <span class="diff_add"> recoding</span> them. Instead, the implementation assumes that the string object</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_137">137-</td><td nowrap="nowrap"> encoding passed in as parameter.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_142">142+</td><td nowrap="nowrap"> <span class="diff_add"> uses the</span> encoding passed in as parameter.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_138">138</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_139">139</td><td nowrap="nowrap">``b`` (integer) [unsigned char]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_140">140</td><td nowrap="nowrap"> Convert a nonnegative Python integer to an unsigned tiny int, stored in a C</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_141">141</td><td nowrap="nowrap"> :ctype:`unsigned char`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_142">142</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_143">143</td><td nowrap="nowrap">``B`` (integer) [unsigned char]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__22">n</a></td><td class="diff_header" id="from3_144">144-</td><td nowrap="nowrap"> Convert a Python integer to a tiny int without overflow checking, stored in<span class="diff_sub"> a C</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__22">n</a></td><td class="diff_header" id="to3_149">149+</td><td nowrap="nowrap"> Convert a Python integer to a tiny int without overflow checking, stored in</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__22"></td><td class="diff_header" id="from3_145">145-</td><td nowrap="nowrap"> :ctype:`unsigned char`.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__22"></td><td class="diff_header" id="to3_150">150+</td><td nowrap="nowrap"> <span class="diff_add"> a C</span> :ctype:`unsigned char`.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_146">146</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_147">147</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_148">148</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_149">149</td><td nowrap="nowrap">``h`` (integer) [short int]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_150">150</td><td nowrap="nowrap"> Convert a Python integer to a C :ctype:`short int`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_151">151</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_152">152</td><td nowrap="nowrap">``H`` (integer) [unsigned short int]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__23">n</a></td><td class="diff_header" id="from3_153">153-</td><td nowrap="nowrap"> Convert a Python integer to a C :ctype:`unsigned short int`, without<span class="diff_sub"> overflow</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__23">n</a></td><td class="diff_header" id="to3_158">158+</td><td nowrap="nowrap"> Convert a Python integer to a C :ctype:`unsigned short int`, without</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_154">154-</td><td nowrap="nowrap"><span class="diff_sub"> checking.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_159">159+</td><td nowrap="nowrap"><span class="diff_add"> overflow checking.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_155">155</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_156">156</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_157">157</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_158">158</td><td nowrap="nowrap">``i`` (integer) [int]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_159">159</td><td nowrap="nowrap"> Convert a Python integer to a plain C :ctype:`int`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_160">160</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_161">161</td><td nowrap="nowrap">``I`` (integer) [unsigned int]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_162">162</td><td nowrap="nowrap"> Convert a Python integer to a C :ctype:`unsigned int`, without overflow</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__23"></td><td class="diff_header" id="from3_163">163</td><td nowrap="nowrap"> checking.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_164">164</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_165">165</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_166">166</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_167">167</td><td nowrap="nowrap">``l`` (integer) [long int]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_168">168</td><td nowrap="nowrap"> Convert a Python integer to a C :ctype:`long int`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_169">169</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to3__24"></td><td class="diff_header" id="from3_170">170</td><td nowrap="nowrap">``k`` (integer) [unsigned long]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__24">n</a></td><td class="diff_header" id="from3_171">171-</td><td nowrap="nowrap"> Convert a Python integer or long integer to a C :ctype:`unsigned long`<span class="diff_sub"> without</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__24">n</a></td><td class="diff_header" id="to3_176">176+</td><td nowrap="nowrap"> Convert a Python integer or long integer to a C :ctype:`unsigned long`</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_172">172-</td><td nowrap="nowrap"> overflow checking.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_177">177+</td><td nowrap="nowrap"> <span class="diff_add"> without</span> overflow checking.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_173">173</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_174">174</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_175">175</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to3__25"></td><td class="diff_header" id="from3_176">176</td><td nowrap="nowrap">``L`` (integer) [PY_LONG_LONG]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_177">177</td><td nowrap="nowrap"> Convert a Python integer to a C :ctype:`long long`. This format is only</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__25">n</a></td><td class="diff_header" id="from3_178">178-</td><td nowrap="nowrap"> available on platforms that support :ctype:`long long` (or :ctype:`_int64`<span class="diff_sub"> on</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__25">n</a></td><td class="diff_header" id="to3_183">183+</td><td nowrap="nowrap"> available on platforms that support :ctype:`long long` (or :ctype:`_int64`</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_179">179-</td><td nowrap="nowrap"> Windows).</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_184">184+</td><td nowrap="nowrap"> <span class="diff_add"> on</span> Windows).</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_180">180</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_181">181</td><td nowrap="nowrap">``K`` (integer) [unsigned PY_LONG_LONG]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_182">182</td><td nowrap="nowrap"> Convert a Python integer or long integer to a C :ctype:`unsigned long long`</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_183">183</td><td nowrap="nowrap"> without overflow checking. This format is only available on platforms that</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__26">n</a></td><td class="diff_header" id="from3_184">184-</td><td nowrap="nowrap"> support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on<span class="diff_sub"> Windows).</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__26">n</a></td><td class="diff_header" id="to3_189">189+</td><td nowrap="nowrap"> support :ctype:`unsigned long long` (or :ctype:`unsigned _int64` on</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_190">190+</td><td nowrap="nowrap"><span class="diff_add"> Windows).</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_185">185</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_186">186</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_187">187</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_188">188</td><td nowrap="nowrap">``n`` (integer) [Py_ssize_t]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_189">189</td><td nowrap="nowrap"> Convert a Python integer or long integer to a C :ctype:`Py_ssize_t`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_190">190</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_191">191</td><td nowrap="nowrap"> .. versionadded:: 2.5</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_192">192</td><td nowrap="nowrap"></td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to3__26"></td><td class="diff_header" id="from3_199">199</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_200">200</td><td nowrap="nowrap">``d`` (float) [double]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_201">201</td><td nowrap="nowrap"> Convert a Python floating point number to a C :ctype:`double`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_202">202</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_203">203</td><td nowrap="nowrap">``D`` (complex) [Py_complex]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_204">204</td><td nowrap="nowrap"> Convert a Python complex number to a C :ctype:`Py_complex` structure.</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__27"></td><td class="diff_header" id="from3_205">205</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_206">206</td><td nowrap="nowrap">``O`` (object) [PyObject \*]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__27">n</a></td><td class="diff_header" id="from3_207">207-</td><td nowrap="nowrap"> Store a Python object (without any conversion) in a C object pointer. The<span class="diff_sub"> C</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__27">n</a></td><td class="diff_header" id="to3_213">213+</td><td nowrap="nowrap"> Store a Python object (without any conversion) in a C object pointer. The</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_208">208-</td><td nowrap="nowrap"> program thus receives the actual object that was passed. The object's<span class="diff_sub"> reference</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_214">214+</td><td nowrap="nowrap"> <span class="diff_add"> C</span> program thus receives the actual object that was passed. The object's</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_209">209-</td><td nowrap="nowrap"> count is not increased. The pointer stored is not *NULL*.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_215">215+</td><td nowrap="nowrap"> <span class="diff_add"> reference</span> count is not increased. The pointer stored is not *NULL*.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_210">210</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to3__28"></td><td class="diff_header" id="from3_211">211</td><td nowrap="nowrap">``O!`` (object) [*typeobject*, PyObject \*]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_212">212</td><td nowrap="nowrap"> Store a Python object in a C object pointer. This is similar to ``O``, but</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__28">n</a></td><td class="diff_header" id="from3_213">213-</td><td nowrap="nowrap"> takes two C arguments: the first is the address of a Python type object,<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__28">n</a></td><td class="diff_header" id="to3_219">219+</td><td nowrap="nowrap"> takes two C arguments: the first is the address of a Python type object,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_214">214-</td><td nowrap="nowrap"> second is the address of the C variable (of type :ctype:`PyObject\*`)<span class="diff_sub"> into which</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_220">220+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> second is the address of the C variable (of type :ctype:`PyObject\*`)</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_215">215-</td><td nowrap="nowrap"> the object pointer is stored. If the Python object does not<span class="diff_sub"> have the required</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_221">221+</td><td nowrap="nowrap"> <span class="diff_add"> into which</span> the object pointer is stored. If the Python object does not</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_216">216-</td><td nowrap="nowrap"> type, :exc:`TypeError` is raised.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_222">222+</td><td nowrap="nowrap"> <span class="diff_add"> have the required</span> type, :exc:`TypeError` is raised.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_217">217</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_218">218</td><td nowrap="nowrap">``O&`` (object) [*converter*, *anything*]</td></tr><tr><td class="diff_next" id="difflib_chg_to3__29"><a href="#difflib_chg_to3__29">n</a></td><td class="diff_header" id="from3_219">219-</td><td nowrap="nowrap"> Convert a Python object to a C variable through a *converter* function.<span class="diff_sub"> This</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__29"><a href="#difflib_chg_to3__29">n</a></td><td class="diff_header" id="to3_225">225+</td><td nowrap="nowrap"> Convert a Python object to a C variable through a *converter* function.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_220">220-</td><td nowrap="nowrap"> takes two arguments: the first is a function, the second is the<span class="diff_sub"> address of a C</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_226">226+</td><td nowrap="nowrap"> <span class="diff_add"> This</span> takes two arguments: the first is a function, the second is the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_221">221-</td><td nowrap="nowrap"> variable (of arbitrary type), converted to :ctype:`void \*`.<span class="diff_sub"> The *converter*</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_227">227+</td><td nowrap="nowrap"> <span class="diff_add"> address of a C</span> variable (of arbitrary type), converted to :ctype:`void \*`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_222">222-</td><td nowrap="nowrap"> function in turn is called as follows::</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_228">228+</td><td nowrap="nowrap"> <span class="diff_add"> The *converter*</span> function in turn is called as follows::</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_223">223</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_224">224</td><td nowrap="nowrap"> status = converter(object, address);</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_225">225</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_226">226</td><td nowrap="nowrap"> where *object* is the Python object to be converted and *address* is the</td></tr><tr><td class="diff_next" id="difflib_chg_to3__30"><a href="#difflib_chg_to3__30">n</a></td><td class="diff_header" id="from3_227">227-</td><td nowrap="nowrap"> :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*`<span class="diff_sub"> function.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__30"><a href="#difflib_chg_to3__30">n</a></td><td class="diff_header" id="to3_233">233+</td><td nowrap="nowrap"> :ctype:`void\*` argument that was passed to the :cfunc:`PyArg_Parse\*`</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_228">228-</td><td nowrap="nowrap"> The returned *status* should be ``1`` for a successful<span class="diff_sub"> conversion and ``0`` if</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_234">234+</td><td nowrap="nowrap"> <span class="diff_add"> function.</span> The returned *status* should be ``1`` for a successful</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_229">229-</td><td nowrap="nowrap"><span class="diff_sub"> the conversion has failed. When the conversion fails, the *converter* function</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_235">235+</td><td nowrap="nowrap"><span class="diff_add"> conversion and ``0`` if the conversion has failed. When the conversion</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_230">230-</td><td nowrap="nowrap"><span class="diff_sub"> should raise an exception and leave the content of *address* unmodified.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_236">236+</td><td nowrap="nowrap"><span class="diff_add"> fails, the *converter* function should raise an exception and leave the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_237">237+</td><td nowrap="nowrap"><span class="diff_add"> content of *address* unmodified.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to3__31"></td><td class="diff_header" id="from3_231">231</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_232">232</td><td nowrap="nowrap">``S`` (string) [PyStringObject \*]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_233">233</td><td nowrap="nowrap"> Like ``O`` but requires that the Python object is a string object. Raises</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__31">n</a></td><td class="diff_header" id="from3_234">234-</td><td nowrap="nowrap"> :exc:`TypeError` if the object is not a string object. The C variable may<span class="diff_sub"> also</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__31">n</a></td><td class="diff_header" id="to3_241">241+</td><td nowrap="nowrap"> :exc:`TypeError` if the object is not a string object. The C variable may</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_235">235-</td><td nowrap="nowrap"> be declared as :ctype:`PyObject\*`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_242">242+</td><td nowrap="nowrap"> <span class="diff_add"> also</span> be declared as :ctype:`PyObject\*`.</td></tr> + <tr><td class="diff_next" id="difflib_chg_to3__32"></td><td class="diff_header" id="from3_236">236</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_237">237</td><td nowrap="nowrap">``U`` (Unicode string) [PyUnicodeObject \*]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_238">238</td><td nowrap="nowrap"> Like ``O`` but requires that the Python object is a Unicode object. Raises</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__32">n</a></td><td class="diff_header" id="from3_239">239-</td><td nowrap="nowrap"> :exc:`TypeError` if the object is not a Unicode object. The C variable may<span class="diff_sub"> also</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__32">n</a></td><td class="diff_header" id="to3_246">246+</td><td nowrap="nowrap"> :exc:`TypeError` if the object is not a Unicode object. The C variable may</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_240">240-</td><td nowrap="nowrap"> be declared as :ctype:`PyObject\*`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_247">247+</td><td nowrap="nowrap"> <span class="diff_add"> also</span> be declared as :ctype:`PyObject\*`.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_241">241</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to3__33"></td><td class="diff_header" id="from3_242">242</td><td nowrap="nowrap">``t#`` (read-only character buffer) [char \*, int]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_243">243</td><td nowrap="nowrap"> Like ``s#``, but accepts any object which implements the read-only buffer</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__33">n</a></td><td class="diff_header" id="from3_244">244-</td><td nowrap="nowrap"> interface. The :ctype:`char\*` variable is set to point to the first byte<span class="diff_sub"> of</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__33">n</a></td><td class="diff_header" id="to3_251">251+</td><td nowrap="nowrap"> interface. The :ctype:`char\*` variable is set to point to the first byte</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_245">245-</td><td nowrap="nowrap"> the buffer, and the :ctype:`int` is set to the length of the buffer.<span class="diff_sub"> Only</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_252">252+</td><td nowrap="nowrap"> <span class="diff_add"> of</span> the buffer, and the :ctype:`int` is set to the length of the buffer.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_246">246-</td><td nowrap="nowrap"> single-segment buffer objects are accepted; :exc:`TypeError` is raised<span class="diff_sub"> for all</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_253">253+</td><td nowrap="nowrap"> <span class="diff_add"> Only</span> single-segment buffer objects are accepted; :exc:`TypeError` is raised</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_247">247-</td><td nowrap="nowrap"><span class="diff_sub"> others.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_254">254+</td><td nowrap="nowrap"><span class="diff_add"> for all others.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_248">248</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to3__34"></td><td class="diff_header" id="from3_249">249</td><td nowrap="nowrap">``w`` (read-write character buffer) [char \*]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__34">n</a></td><td class="diff_header" id="from3_250">250-</td><td nowrap="nowrap"> Similar to ``s``, but accepts any object which implements the read-write<span class="diff_sub"> buffer</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__34">n</a></td><td class="diff_header" id="to3_257">257+</td><td nowrap="nowrap"> Similar to ``s``, but accepts any object which implements the read-write</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_251">251-</td><td nowrap="nowrap"> interface. The caller must determine the length of the buffer by<span class="diff_sub"> other means,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_258">258+</td><td nowrap="nowrap"> <span class="diff_add"> buffer</span> interface. The caller must determine the length of the buffer by</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_252">252-</td><td nowrap="nowrap"> or use ``w#`` instead. Only single-segment buffer objects are<span class="diff_sub"> accepted;</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_259">259+</td><td nowrap="nowrap"> <span class="diff_add"> other means,</span> or use ``w#`` instead. Only single-segment buffer objects are</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_253">253-</td><td nowrap="nowrap"> :exc:`TypeError` is raised for all others.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_260">260+</td><td nowrap="nowrap"> <span class="diff_add"> accepted;</span> :exc:`TypeError` is raised for all others.</td></tr> + <tr><td class="diff_next" id="difflib_chg_to3__35"></td><td class="diff_header" id="from3_254">254</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_255">255</td><td nowrap="nowrap">``w#`` (read-write character buffer) [char \*, Py_ssize_t]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_256">256</td><td nowrap="nowrap"> Like ``s#``, but accepts any object which implements the read-write buffer</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__35">n</a></td><td class="diff_header" id="from3_257">257-</td><td nowrap="nowrap"> interface. The :ctype:`char \*` variable is set to point to the first byte<span class="diff_sub"> of</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__35">n</a></td><td class="diff_header" id="to3_264">264+</td><td nowrap="nowrap"> interface. The :ctype:`char \*` variable is set to point to the first byte</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_258">258-</td><td nowrap="nowrap"> the buffer, and the :ctype:`i<span class="diff_chg">n</span>t` is set to the length of the<span class="diff_sub"> buffer. Only</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_265">265+</td><td nowrap="nowrap"> <span class="diff_add"> of</span> the buffer, and the :ctype:`<span class="diff_add">Py_ss</span>i<span class="diff_chg">ze_</span>t` is set to the length of the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_259">259-</td><td nowrap="nowrap"> single-segment buffer objects are accepted; :exc:`TypeError`<span class="diff_sub"> is raised for all</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_266">266+</td><td nowrap="nowrap"> <span class="diff_add"> buffer. Only</span> single-segment buffer objects are accepted; :exc:`TypeError`</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__36"></td><td class="diff_header" id="from3_260">260-</td><td nowrap="nowrap"><span class="diff_sub"> others.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__36"></td><td class="diff_header" id="to3_267">267+</td><td nowrap="nowrap"><span class="diff_add"> is raised for all others.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_261">261</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__36">n</a></td><td class="diff_header" id="from3_262">262-</td><td nowrap="nowrap">``w*`` (read-write byte-oriented buffer) [Py_buffer<span class="diff_sub"> \*</span>]</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__36">n</a></td><td class="diff_header" id="to3_269">269+</td><td nowrap="nowrap">``w*`` (read-write byte-oriented buffer) [Py_buffer]</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_263">263</td><td nowrap="nowrap"> This is to ``w`` what ``s*`` is to ``s``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_264">264</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_265">265</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__37"></td><td class="diff_header" id="from3_266">266</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_267">267</td><td nowrap="nowrap">``(items)`` (tuple) [*matching-items*]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__37">n</a></td><td class="diff_header" id="from3_268">268-</td><td nowrap="nowrap"> The object must be a Python sequence whose length is the number of format<span class="diff_sub"> units</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__37">n</a></td><td class="diff_header" id="to3_275">275+</td><td nowrap="nowrap"> The object must be a Python sequence whose length is the number of format</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_269">269-</td><td nowrap="nowrap"> in *items*. The C arguments must correspond to the individual format<span class="diff_sub"> units in</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_276">276+</td><td nowrap="nowrap"> <span class="diff_add"> units</span> in *items*. The C arguments must correspond to the individual format</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_270">270-</td><td nowrap="nowrap"> *items*. Format units for sequences may be nested.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_277">277+</td><td nowrap="nowrap"> <span class="diff_add"> units in</span> *items*. Format units for sequences may be nested.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_271">271</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_272">272</td><td nowrap="nowrap"> .. note::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_273">273</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__38">n</a></td><td class="diff_header" id="from3_274">274-</td><td nowrap="nowrap"> Prior to Python version 1.5.2, this format specifier only accepted a<span class="diff_sub"> tuple</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__38">n</a></td><td class="diff_header" id="to3_281">281+</td><td nowrap="nowrap"> Prior to Python version 1.5.2, this format specifier only accepted a</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__38"></td><td class="diff_header" id="from3_275">275-</td><td nowrap="nowrap"> containing the individual parameters, not an arbitrary sequence.<span class="diff_sub"> Code which</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__38"></td><td class="diff_header" id="to3_282">282+</td><td nowrap="nowrap"> <span class="diff_add"> tuple</span> containing the individual parameters, not an arbitrary sequence.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_276">276-</td><td nowrap="nowrap"> previously caused :exc:`TypeError` to be raised here may now<span class="diff_sub"> proceed without an</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_283">283+</td><td nowrap="nowrap"> <span class="diff_add"> Code which</span> previously caused :exc:`TypeError` to be raised here may now</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_277">277-</td><td nowrap="nowrap"> exception. This is not expected to be a problem for<span class="diff_sub"> existing code.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_284">284+</td><td nowrap="nowrap"> <span class="diff_add"> proceed without an</span> exception. This is not expected to be a problem for</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_285">285+</td><td nowrap="nowrap"><span class="diff_add"> existing code.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_278">278</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_279">279</td><td nowrap="nowrap">It is possible to pass Python long integers where integers are requested;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_280">280</td><td nowrap="nowrap">however no proper range checking is done --- the most significant bits are</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__39"></td><td class="diff_header" id="from3_281">281</td><td nowrap="nowrap">silently truncated when the receiving field is too small to receive the value</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__39">n</a></td><td class="diff_header" id="from3_282">282-</td><td nowrap="nowrap">(actually, the semantics are inherited from downcasts in C --- your mileage<span class="diff_sub"> may</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__39">n</a></td><td class="diff_header" id="to3_290">290+</td><td nowrap="nowrap">(actually, the semantics are inherited from downcasts in C --- your mileage</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_283">283-</td><td nowrap="nowrap">vary).</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_291">291+</td><td nowrap="nowrap"><span class="diff_add">may </span>vary).</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_284">284</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_285">285</td><td nowrap="nowrap">A few other characters have a meaning in a format string. These may not occur</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_286">286</td><td nowrap="nowrap">inside nested parentheses. They are:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_287">287</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to3__40"></td><td class="diff_header" id="from3_288">288</td><td nowrap="nowrap">``|``</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__40">n</a></td><td class="diff_header" id="from3_289">289-</td><td nowrap="nowrap"> Indicates that the remaining arguments in the Python argument list are<span class="diff_sub"> optional.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__40">n</a></td><td class="diff_header" id="to3_297">297+</td><td nowrap="nowrap"> Indicates that the remaining arguments in the Python argument list are</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_290">290-</td><td nowrap="nowrap"> The C variables corresponding to optional arguments should be<span class="diff_sub"> initialized to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_298">298+</td><td nowrap="nowrap"> <span class="diff_add"> optional.</span> The C variables corresponding to optional arguments should be</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_291">291-</td><td nowrap="nowrap"> their default value --- when an optional argument is not<span class="diff_sub"> specified,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_299">299+</td><td nowrap="nowrap"> <span class="diff_add"> initialized to</span> their default value --- when an optional argument is not</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_292">292-</td><td nowrap="nowrap"> :cfunc:`PyArg_ParseTuple` does not touch the contents of the<span class="diff_sub"> corresponding C</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_300">300+</td><td nowrap="nowrap"> <span class="diff_add"> specified,</span> :cfunc:`PyArg_ParseTuple` does not touch the contents of the</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__41"></td><td class="diff_header" id="from3_293">293-</td><td nowrap="nowrap"><span class="diff_sub"> variable(s).</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__41"></td><td class="diff_header" id="to3_301">301+</td><td nowrap="nowrap"><span class="diff_add"> corresponding C variable(s).</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_294">294</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_295">295</td><td nowrap="nowrap">``:``</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__41">n</a></td><td class="diff_header" id="from3_296">296-</td><td nowrap="nowrap"> The list of format units ends here; the string after the colon is used as<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__41">n</a></td><td class="diff_header" id="to3_304">304+</td><td nowrap="nowrap"> The list of format units ends here; the string after the colon is used as</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_297">297-</td><td nowrap="nowrap"> function name in error messages (the "associated value" of the<span class="diff_sub"> exception that</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_305">305+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> function name in error messages (the "associated value" of the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_298">298-</td><td nowrap="nowrap"> :cfunc:`PyArg_ParseTuple` raises).</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_306">306+</td><td nowrap="nowrap"> <span class="diff_add"> exception that</span> :cfunc:`PyArg_ParseTuple` raises).</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_299">299</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_300">300</td><td nowrap="nowrap">``;``</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__42">n</a></td><td class="diff_header" id="from3_301">301-</td><td nowrap="nowrap"> The list of format units ends here; the string after the semicolon is used<span class="diff_sub"> as</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__42">n</a></td><td class="diff_header" id="to3_309">309+</td><td nowrap="nowrap"> The list of format units ends here; the string after the semicolon is used</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__42"></td><td class="diff_header" id="from3_302">302-</td><td nowrap="nowrap"> the error message *instead* of the default error message. ``:`` and<span class="diff_sub"> ``;``</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__42"></td><td class="diff_header" id="to3_310">310+</td><td nowrap="nowrap"> <span class="diff_add"> as</span> the error message *instead* of the default error message. ``:`` and</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_303">303-</td><td nowrap="nowrap"> mutually exclude each other.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_311">311+</td><td nowrap="nowrap"> <span class="diff_add"> ``;``</span> mutually exclude each other.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_304">304</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_305">305</td><td nowrap="nowrap">Note that any Python object references which are provided to the caller are</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__43"></td><td class="diff_header" id="from3_306">306</td><td nowrap="nowrap">*borrowed* references; do not decrement their reference count!</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_307">307</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_308">308</td><td nowrap="nowrap">Additional arguments passed to these functions must be addresses of variables</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_309">309</td><td nowrap="nowrap">whose type is determined by the format string; these are used to store values</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__43">n</a></td><td class="diff_header" id="from3_310">310-</td><td nowrap="nowrap">from the input tuple. There are a few cases, as described in the list of<span class="diff_sub"> format</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__43">n</a></td><td class="diff_header" id="to3_318">318+</td><td nowrap="nowrap">from the input tuple. There are a few cases, as described in the list of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_311">311-</td><td nowrap="nowrap">units above, where these parameters are used as input values; they<span class="diff_sub"> should match</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_319">319+</td><td nowrap="nowrap"><span class="diff_add">format </span>units above, where these parameters are used as input values; they</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_312">312-</td><td nowrap="nowrap">what is specified for the corresponding format unit in that case.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_320">320+</td><td nowrap="nowrap"><span class="diff_add">should match </span>what is specified for the corresponding format unit in that case.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_313">313</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__44">n</a></td><td class="diff_header" id="from3_314">314-</td><td nowrap="nowrap">For the conversion to succeed, the *arg* object must match the format</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__44">n</a></td><td class="diff_header" id="to3_322">322+</td><td nowrap="nowrap">For the conversion to succeed, the *arg* object must match the format<span class="diff_add"> and the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_315">315-</td><td nowrap="nowrap"><span class="diff_sub">and the format must be exhausted. On success, the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_323">323+</td><td nowrap="nowrap"><span class="diff_add">format must be exhausted. On success, the :cfunc:`PyArg_Parse\*` functions</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_316">316-</td><td nowrap="nowrap"><span class="diff_sub">:cfunc:`PyArg_Parse\*` functions return true, otherwise they return</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_324">324+</td><td nowrap="nowrap"><span class="diff_add">return true, otherwise they return false and raise an appropriate exception.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__44"></td><td class="diff_header" id="from3_317">317-</td><td nowrap="nowrap"><span class="diff_sub">false and raise an appropriate exception. When the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_318">318-</td><td nowrap="nowrap">:cfunc:`PyArg_Parse\*` functions fail due to conversion failure in<span class="diff_sub"> one</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_325">325+</td><td nowrap="nowrap"><span class="diff_add">When the </span>:cfunc:`PyArg_Parse\*` functions fail due to conversion failure in</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_319">319-</td><td nowrap="nowrap">of the format units, the variables at the addresses corresponding to that</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_326">326+</td><td nowrap="nowrap"><span class="diff_add">one </span>of the format units, the variables at the addresses corresponding to that</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_320">320</td><td nowrap="nowrap">and the following format units are left untouched.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_321">321</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_322">322</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_323">323</td><td nowrap="nowrap">.. cfunction:: int PyArg_ParseTuple(PyObject *args, const char *format, ...)</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__45"></td><td class="diff_header" id="from3_324">324</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__45">n</a></td><td class="diff_header" id="from3_325">325-</td><td nowrap="nowrap"> Parse the parameters of a function that takes only positional parameters<span class="diff_sub"> into</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__45">n</a></td><td class="diff_header" id="to3_332">332+</td><td nowrap="nowrap"> Parse the parameters of a function that takes only positional parameters</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_326">326-</td><td nowrap="nowrap"> local variables. Returns true on success; on failure, it returns<span class="diff_sub"> false and</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_333">333+</td><td nowrap="nowrap"> <span class="diff_add"> into</span> local variables. Returns true on success; on failure, it returns</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_327">327-</td><td nowrap="nowrap"> raises the appropriate exception.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_334">334+</td><td nowrap="nowrap"> <span class="diff_add"> false and</span> raises the appropriate exception.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_328">328</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_329">329</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_330">330</td><td nowrap="nowrap">.. cfunction:: int PyArg_VaParse(PyObject *args, const char *format, va_list vargs)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_331">331</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__46">n</a></td><td class="diff_header" id="from3_332">332-</td><td nowrap="nowrap"> Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list<span class="diff_sub"> rather</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__46">n</a></td><td class="diff_header" id="to3_339">339+</td><td nowrap="nowrap"> Identical to :cfunc:`PyArg_ParseTuple`, except that it accepts a va_list</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_333">333-</td><td nowrap="nowrap"> than a variable number of arguments.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_340">340+</td><td nowrap="nowrap"> <span class="diff_add"> rather</span> than a variable number of arguments.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_334">334</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_335">335</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_336">336</td><td nowrap="nowrap">.. cfunction:: int PyArg_ParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], ...)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_337">337</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_338">338</td><td nowrap="nowrap"> Parse the parameters of a function that takes both positional and keyword</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_339">339</td><td nowrap="nowrap"> parameters into local variables. Returns true on success; on failure, it</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_340">340</td><td nowrap="nowrap"> returns false and raises the appropriate exception.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_341">341</td><td nowrap="nowrap"></td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to3__46"></td><td class="diff_header" id="from3_343">343</td><td nowrap="nowrap">.. cfunction:: int PyArg_VaParseTupleAndKeywords(PyObject *args, PyObject *kw, const char *format, char *keywords[], va_list vargs)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_344">344</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_345">345</td><td nowrap="nowrap"> Identical to :cfunc:`PyArg_ParseTupleAndKeywords`, except that it accepts a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_346">346</td><td nowrap="nowrap"> va_list rather than a variable number of arguments.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_347">347</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_348">348</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_349">349</td><td nowrap="nowrap">.. cfunction:: int PyArg_Parse(PyObject *args, const char *format, ...)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_350">350</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__47">n</a></td><td class="diff_header" id="from3_351">351-</td><td nowrap="nowrap"> Function used to deconstruct the argument lists of "old-style" functions<span class="diff_sub"> ---</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__47">n</a></td><td class="diff_header" id="to3_358">358+</td><td nowrap="nowrap"> Function used to deconstruct the argument lists of "old-style" functions</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_352">352-</td><td nowrap="nowrap"> these are functions which use the :const:`METH_OLDARGS` parameter<span class="diff_sub"> parsing</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_359">359+</td><td nowrap="nowrap"> <span class="diff_add"> ---</span> these are functions which use the :const:`METH_OLDARGS` parameter</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_353">353-</td><td nowrap="nowrap"> method. This is not recommended for use in parameter parsing in<span class="diff_sub"> new code, and</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_360">360+</td><td nowrap="nowrap"> <span class="diff_add"> parsing</span> method. This is not recommended for use in parameter parsing in</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_354">354-</td><td nowrap="nowrap"> most code in the standard interpreter has been modified to no<span class="diff_sub"> longer use this</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_361">361+</td><td nowrap="nowrap"> <span class="diff_add"> new code, and</span> most code in the standard interpreter has been modified to no</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__47"></td><td class="diff_header" id="from3_355">355-</td><td nowrap="nowrap"><span class="diff_sub"> for that purpose. It does remain a convenient way to decompose other tuples,</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__47"></td><td class="diff_header" id="to3_362">362+</td><td nowrap="nowrap"><span class="diff_add"> longer use this for that purpose. It does remain a convenient way to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_356">356-</td><td nowrap="nowrap"><span class="diff_sub"> however, and may continue to be used for that purpose.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_363">363+</td><td nowrap="nowrap"><span class="diff_add"> decompose other tuples, however, and may continue to be used for that</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_364">364+</td><td nowrap="nowrap"><span class="diff_add"> purpose.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_357">357</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_358">358</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_359">359</td><td nowrap="nowrap">.. cfunction:: int PyArg_UnpackTuple(PyObject *args, const char *name, Py_ssize_t min, Py_ssize_t max, ...)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_360">360</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_361">361</td><td nowrap="nowrap"> A simpler form of parameter retrieval which does not use a format string to</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__48">n</a></td><td class="diff_header" id="from3_362">362-</td><td nowrap="nowrap"> specify the types of the arguments. Functions which use this method to<span class="diff_sub"> retrieve</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__48">n</a></td><td class="diff_header" id="to3_370">370+</td><td nowrap="nowrap"> specify the types of the arguments. Functions which use this method to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_363">363-</td><td nowrap="nowrap"> their parameters should be declared as :const:`METH_VARARGS` in<span class="diff_sub"> function or</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_371">371+</td><td nowrap="nowrap"> <span class="diff_add"> retrieve</span> their parameters should be declared as :const:`METH_VARARGS` in</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_364">364-</td><td nowrap="nowrap"> method tables. The tuple containing the actual parameters<span class="diff_sub"> should be passed as</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_372">372+</td><td nowrap="nowrap"> <span class="diff_add"> function or</span> method tables. The tuple containing the actual parameters</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_365">365-</td><td nowrap="nowrap"><span class="diff_sub"> *args*; it must actually be a tuple. The length of the tuple must be at least</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_373">373+</td><td nowrap="nowrap"><span class="diff_add"> should be passed as *args*; it must actually be a tuple. The length of the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_366">366-</td><td nowrap="nowrap"><span class="diff_sub"> *min* and no more than *max*; *min* and *max* may be equal. Additional</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_374">374+</td><td nowrap="nowrap"><span class="diff_add"> tuple must be at least *min* and no more than *max*; *min* and *max* may be</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__48"></td><td class="diff_header" id="from3_367">367-</td><td nowrap="nowrap"><span class="diff_sub"> arguments must be passed to the function, each of which should be a pointer to a</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__48"></td><td class="diff_header" id="to3_375">375+</td><td nowrap="nowrap"><span class="diff_add"> equal. Additional arguments must be passed to the function, each of which</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_368">368-</td><td nowrap="nowrap"><span class="diff_sub"> :ctype:`PyObject\*` variable; these will be filled in with the values from</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_376">376+</td><td nowrap="nowrap"><span class="diff_add"> should be a pointer to a :ctype:`PyObject\*` variable; these will be filled</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_369">369-</td><td nowrap="nowrap"><span class="diff_sub"> *args*; they will contain borrowed references. The variables which correspond</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_377">377+</td><td nowrap="nowrap"><span class="diff_add"> in with the values from *args*; they will contain borrowed references. The</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_370">370-</td><td nowrap="nowrap"><span class="diff_sub"> to optional parameters not given by *args* will not be filled in; these should</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_378">378+</td><td nowrap="nowrap"><span class="diff_add"> variables which correspond to optional parameters not given by *args* will</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_371">371-</td><td nowrap="nowrap"><span class="diff_sub"> be initialized by the caller. This function returns true on success and false if</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_379">379+</td><td nowrap="nowrap"><span class="diff_add"> not be filled in; these should be initialized by the caller. This function</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_372">372-</td><td nowrap="nowrap"><span class="diff_sub"> *args* is not a tuple or contains the wrong number of elements; an exception</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_380">380+</td><td nowrap="nowrap"><span class="diff_add"> returns true on success and false if *args* is not a tuple or contains the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_373">373-</td><td nowrap="nowrap"><span class="diff_sub"> will be set if there was a failure.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_381">381+</td><td nowrap="nowrap"><span class="diff_add"> wrong number of elements; an exception will be set if there was a failure.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_374">374</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__49">n</a></td><td class="diff_header" id="from3_375">375-</td><td nowrap="nowrap"> This is an example of the use of this function, taken from the sources for<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__49">n</a></td><td class="diff_header" id="to3_383">383+</td><td nowrap="nowrap"> This is an example of the use of this function, taken from the sources for</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_376">376-</td><td nowrap="nowrap"> :mod:`_weakref` helper module for weak references::</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_384">384+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> :mod:`_weakref` helper module for weak references::</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_377">377</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_378">378</td><td nowrap="nowrap"> static PyObject *</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_379">379</td><td nowrap="nowrap"> weakref_ref(PyObject *self, PyObject *args)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_380">380</td><td nowrap="nowrap"> {</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_381">381</td><td nowrap="nowrap"> PyObject *object;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_382">382</td><td nowrap="nowrap"> PyObject *callback = NULL;</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__49"></td><td class="diff_header" id="from3_383">383</td><td nowrap="nowrap"> PyObject *result = NULL;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_384">384</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_385">385</td><td nowrap="nowrap"> if (PyArg_UnpackTuple(args, "ref", 1, 2, &object, &callback)) {</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_386">386</td><td nowrap="nowrap"> result = PyWeakref_NewRef(object, callback);</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_387">387</td><td nowrap="nowrap"> }</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_388">388</td><td nowrap="nowrap"> return result;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_389">389</td><td nowrap="nowrap"> }</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__50"></td><td class="diff_header" id="from3_390">390</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__50">n</a></td><td class="diff_header" id="from3_391">391-</td><td nowrap="nowrap"> The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely<span class="diff_sub"> equivalent to</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__50">n</a></td><td class="diff_header" id="to3_399">399+</td><td nowrap="nowrap"> The call to :cfunc:`PyArg_UnpackTuple` in this example is entirely</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_392">392-</td><td nowrap="nowrap"> this call to :cfunc:`PyArg_ParseTuple`::</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_400">400+</td><td nowrap="nowrap"> <span class="diff_add"> equivalent to</span> this call to :cfunc:`PyArg_ParseTuple`::</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_393">393</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_394">394</td><td nowrap="nowrap"> PyArg_ParseTuple(args, "O| O:ref", &object, &callback)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_395">395</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_396">396</td><td nowrap="nowrap"> .. versionadded:: 2.2</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__51"></td><td class="diff_header" id="from3_397">397</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__51">n</a></td><td class="diff_header" id="to3_406">406+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_407">407+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *min* and *max*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_408">408+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_409">409+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to3__52"></td><td class="diff_header" id="from3_398">398</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_399">399</td><td nowrap="nowrap">.. cfunction:: PyObject* Py_BuildValue(const char *format, ...)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_400">400</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__52">n</a></td><td class="diff_header" id="from3_401">401-</td><td nowrap="nowrap"> Create a new value based on a format string similar to those accepted by<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__52">n</a></td><td class="diff_header" id="to3_413">413+</td><td nowrap="nowrap"> Create a new value based on a format string similar to those accepted by</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_402">402-</td><td nowrap="nowrap"> :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.<span class="diff_sub"> Returns</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_414">414+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> :cfunc:`PyArg_Parse\*` family of functions and a sequence of values.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_403">403-</td><td nowrap="nowrap"> the value or *NULL* in the case of an error; an exception will be<span class="diff_sub"> raised if</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_415">415+</td><td nowrap="nowrap"> <span class="diff_add"> Returns</span> the value or *NULL* in the case of an error; an exception will be</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_404">404-</td><td nowrap="nowrap"> *NULL* is returned.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_416">416+</td><td nowrap="nowrap"> <span class="diff_add"> raised if</span> *NULL* is returned.</td></tr> + <tr><td class="diff_next" id="difflib_chg_to3__53"></td><td class="diff_header" id="from3_405">405</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__53">n</a></td><td class="diff_header" id="from3_406">406-</td><td nowrap="nowrap"> :cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple<span class="diff_sub"> only if</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__53">n</a></td><td class="diff_header" id="to3_418">418+</td><td nowrap="nowrap"> :cfunc:`Py_BuildValue` does not always build a tuple. It builds a tuple</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_407">407-</td><td nowrap="nowrap"> its format string contains two or more format units. If the format<span class="diff_sub"> string is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_419">419+</td><td nowrap="nowrap"> <span class="diff_add"> only if</span> its format string contains two or more format units. If the format</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_408">408-</td><td nowrap="nowrap"> empty, it returns ``None``; if it contains exactly one format<span class="diff_sub"> unit, it returns</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_420">420+</td><td nowrap="nowrap"> <span class="diff_add"> string is</span> empty, it returns ``None``; if it contains exactly one format</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_409">409-</td><td nowrap="nowrap"><span class="diff_sub"> whatever object is described by that format unit. To force it to return a tuple</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_421">421+</td><td nowrap="nowrap"><span class="diff_add"> unit, it returns whatever object is described by that format unit. To</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_410">410-</td><td nowrap="nowrap"><span class="diff_sub"> of size 0 or one, parenthesize the format string.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_422">422+</td><td nowrap="nowrap"><span class="diff_add"> force it to return a tuple of size 0 or one, parenthesize the format</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_423">423+</td><td nowrap="nowrap"><span class="diff_add"> string.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_411">411</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next" id="difflib_chg_to3__54"><a href="#difflib_chg_to3__54">n</a></td><td class="diff_header" id="from3_412">412-</td><td nowrap="nowrap"> When memory buffers are passed as parameters to supply data to build<span class="diff_sub"> objects, as</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__54"><a href="#difflib_chg_to3__54">n</a></td><td class="diff_header" id="to3_425">425+</td><td nowrap="nowrap"> When memory buffers are passed as parameters to supply data to build</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_413">413-</td><td nowrap="nowrap"> for the ``s`` and ``s#`` formats, the required data is copied.<span class="diff_sub"> Buffers provided</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_426">426+</td><td nowrap="nowrap"> <span class="diff_add"> objects, as</span> for the ``s`` and ``s#`` formats, the required data is copied.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_414">414-</td><td nowrap="nowrap"> by the caller are never referenced by the objects created<span class="diff_sub"> by</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_427">427+</td><td nowrap="nowrap"> <span class="diff_add"> Buffers provided</span> by the caller are never referenced by the objects created</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_415">415-</td><td nowrap="nowrap"> :cfunc:`Py_BuildValue`. In other words, if your code invokes<span class="diff_sub"> :cfunc:`malloc`</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_428">428+</td><td nowrap="nowrap"> <span class="diff_add"> by</span> :cfunc:`Py_BuildValue`. In other words, if your code invokes</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_416">416-</td><td nowrap="nowrap"> and passes the allocated memory to :cfunc:`Py_BuildValue`,<span class="diff_sub"> your code is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_429">429+</td><td nowrap="nowrap"> <span class="diff_add"> :cfunc:`malloc`</span> and passes the allocated memory to :cfunc:`Py_BuildValue`,</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__55"></td><td class="diff_header" id="from3_417">417-</td><td nowrap="nowrap"> responsible for calling :cfunc:`free` for that memory once</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__55"></td><td class="diff_header" id="to3_430">430+</td><td nowrap="nowrap"> <span class="diff_add"> your code is</span> responsible for calling :cfunc:`free` for that memory once</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_418">418</td><td nowrap="nowrap"> :cfunc:`Py_BuildValue` returns.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_419">419</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__55">n</a></td><td class="diff_header" id="from3_420">420-</td><td nowrap="nowrap"> In the following description, the quoted form is the format unit; the entry<span class="diff_sub"> in</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__55">n</a></td><td class="diff_header" id="to3_433">433+</td><td nowrap="nowrap"> In the following description, the quoted form is the format unit; the entry</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_421">421-</td><td nowrap="nowrap"> (round) parentheses is the Python object type that the format unit will<span class="diff_sub"> return;</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_434">434+</td><td nowrap="nowrap"> <span class="diff_add"> in</span> (round) parentheses is the Python object type that the format unit will</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__56"></td><td class="diff_header" id="from3_422">422-</td><td nowrap="nowrap"> and the entry in [square] brackets is the type of the C value(s) to<span class="diff_sub"> be passed.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__56"></td><td class="diff_header" id="to3_435">435+</td><td nowrap="nowrap"> <span class="diff_add"> return;</span> and the entry in [square] brackets is the type of the C value(s) to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_436">436+</td><td nowrap="nowrap"><span class="diff_add"> be passed.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_423">423</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__56">n</a></td><td class="diff_header" id="from3_424">424-</td><td nowrap="nowrap"> The characters space, tab, colon and comma are ignored in format strings<span class="diff_sub"> (but</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__56">n</a></td><td class="diff_header" id="to3_438">438+</td><td nowrap="nowrap"> The characters space, tab, colon and comma are ignored in format strings</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__57"></td><td class="diff_header" id="from3_425">425-</td><td nowrap="nowrap"> not within format units such as ``s#``). This can be used to make<span class="diff_sub"> long format</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__57"></td><td class="diff_header" id="to3_439">439+</td><td nowrap="nowrap"> <span class="diff_add"> (but</span> not within format units such as ``s#``). This can be used to make</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_426">426-</td><td nowrap="nowrap"> strings a tad more readable.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_440">440+</td><td nowrap="nowrap"> <span class="diff_add"> long format</span> strings a tad more readable.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_427">427</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_428">428</td><td nowrap="nowrap"> ``s`` (string) [char \*]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__57">n</a></td><td class="diff_header" id="from3_429">429-</td><td nowrap="nowrap"> Convert a null-terminated C string to a Python object. If the C string<span class="diff_sub"> pointer</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__57">n</a></td><td class="diff_header" id="to3_443">443+</td><td nowrap="nowrap"> Convert a null-terminated C string to a Python object. If the C string</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_430">430-</td><td nowrap="nowrap"> is *NULL*, ``None`` is used.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_444">444+</td><td nowrap="nowrap"> <span class="diff_add"> pointer</span> is *NULL*, ``None`` is used.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_431">431</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_432">432</td><td nowrap="nowrap"> ``s#`` (string) [char \*, int]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__58">n</a></td><td class="diff_header" id="from3_433">433-</td><td nowrap="nowrap"> Convert a C string and its length to a Python object. If the C string<span class="diff_sub"> pointer</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__58">n</a></td><td class="diff_header" id="to3_447">447+</td><td nowrap="nowrap"> Convert a C string and its length to a Python object. If the C string</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_434">434-</td><td nowrap="nowrap"> is *NULL*, the length is ignored and ``None`` is returned.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_448">448+</td><td nowrap="nowrap"> <span class="diff_add"> pointer</span> is *NULL*, the length is ignored and ``None`` is returned.</td></tr> + <tr><td class="diff_next" id="difflib_chg_to3__58"></td><td class="diff_header" id="from3_435">435</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_436">436</td><td nowrap="nowrap"> ``z`` (string or ``None``) [char \*]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_437">437</td><td nowrap="nowrap"> Same as ``s``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_438">438</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_439">439</td><td nowrap="nowrap"> ``z#`` (string or ``None``) [char \*, int]</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__59"></td><td class="diff_header" id="from3_440">440</td><td nowrap="nowrap"> Same as ``s#``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_441">441</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_442">442</td><td nowrap="nowrap"> ``u`` (Unicode string) [Py_UNICODE \*]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__59">n</a></td><td class="diff_header" id="from3_443">443-</td><td nowrap="nowrap"> Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a<span class="diff_sub"> Python</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__59">n</a></td><td class="diff_header" id="to3_457">457+</td><td nowrap="nowrap"> Convert a null-terminated buffer of Unicode (UCS-2 or UCS-4) data to a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_444">444-</td><td nowrap="nowrap"> Unicode object. If the Unicode buffer pointer is *NULL*,<span class="diff_sub"> ``None`` is returned.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_458">458+</td><td nowrap="nowrap"> <span class="diff_add"> Python</span> Unicode object. If the Unicode buffer pointer is *NULL*,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_459">459+</td><td nowrap="nowrap"><span class="diff_add"> ``None`` is returned.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_445">445</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_446">446</td><td nowrap="nowrap"> ``u#`` (Unicode string) [Py_UNICODE \*, int]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__60">n</a></td><td class="diff_header" id="from3_447">447-</td><td nowrap="nowrap"> Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a<span class="diff_sub"> Python</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__60">n</a></td><td class="diff_header" id="to3_462">462+</td><td nowrap="nowrap"> Convert a Unicode (UCS-2 or UCS-4) data buffer and its length to a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_448">448-</td><td nowrap="nowrap"> Unicode object. If the Unicode buffer pointer is *NULL*, the<span class="diff_sub"> length is ignored</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_463">463+</td><td nowrap="nowrap"> <span class="diff_add"> Python</span> Unicode object. If the Unicode buffer pointer is *NULL*, the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_449">449-</td><td nowrap="nowrap"> and ``None`` is returned.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_464">464+</td><td nowrap="nowrap"> <span class="diff_add"> length is ignored</span> and ``None`` is returned.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_450">450</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_451">451</td><td nowrap="nowrap"> ``i`` (integer) [int]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_452">452</td><td nowrap="nowrap"> Convert a plain C :ctype:`int` to a Python integer object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_453">453</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_454">454</td><td nowrap="nowrap"> ``b`` (integer) [char]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_455">455</td><td nowrap="nowrap"> Convert a plain C :ctype:`char` to a Python integer object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_456">456</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_457">457</td><td nowrap="nowrap"> ``h`` (integer) [short int]</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to3__60"></td><td class="diff_header" id="from3_462">462</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_463">463</td><td nowrap="nowrap"> ``B`` (integer) [unsigned char]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_464">464</td><td nowrap="nowrap"> Convert a C :ctype:`unsigned char` to a Python integer object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_465">465</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to3__61"></td><td class="diff_header" id="from3_466">466</td><td nowrap="nowrap"> ``H`` (integer) [unsigned short int]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_467">467</td><td nowrap="nowrap"> Convert a C :ctype:`unsigned short int` to a Python integer object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_468">468</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_469">469</td><td nowrap="nowrap"> ``I`` (integer/long) [unsigned int]</td></tr><tr><td class="diff_next" id="difflib_chg_to3__62"><a href="#difflib_chg_to3__61">n</a></td><td class="diff_header" id="from3_470">470-</td><td nowrap="nowrap"> Convert a C :ctype:`unsigned int` to a Python integer object or a Python<span class="diff_sub"> long</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__62"><a href="#difflib_chg_to3__61">n</a></td><td class="diff_header" id="to3_485">485+</td><td nowrap="nowrap"> Convert a C :ctype:`unsigned int` to a Python integer object or a Python</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_471">471-</td><td nowrap="nowrap"> integer object, if it is larger than ``sys.maxint``.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_486">486+</td><td nowrap="nowrap"> <span class="diff_add"> long</span> integer object, if it is larger than ``sys.maxint``.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_472">472</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_473">473</td><td nowrap="nowrap"> ``k`` (integer/long) [unsigned long]</td></tr><tr><td class="diff_next" id="difflib_chg_to3__63"><a href="#difflib_chg_to3__62">n</a></td><td class="diff_header" id="from3_474">474-</td><td nowrap="nowrap"> Convert a C :ctype:`unsigned long` to a Python integer object or a<span class="diff_sub"> Python long</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__63"><a href="#difflib_chg_to3__62">n</a></td><td class="diff_header" id="to3_489">489+</td><td nowrap="nowrap"> Convert a C :ctype:`unsigned long` to a Python integer object or a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_475">475-</td><td nowrap="nowrap"> integer object, if it is larger than ``sys.maxint``.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_490">490+</td><td nowrap="nowrap"> <span class="diff_add"> Python long</span> integer object, if it is larger than ``sys.maxint``.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_476">476</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_477">477</td><td nowrap="nowrap"> ``L`` (long) [PY_LONG_LONG]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__63">n</a></td><td class="diff_header" id="from3_478">478-</td><td nowrap="nowrap"> Convert a C :ctype:`long long` to a Python long integer object. Only<span class="diff_sub"> available</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__63">n</a></td><td class="diff_header" id="to3_493">493+</td><td nowrap="nowrap"> Convert a C :ctype:`long long` to a Python long integer object. Only</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_479">479-</td><td nowrap="nowrap"> on platforms that support :ctype:`long long`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_494">494+</td><td nowrap="nowrap"> <span class="diff_add"> available</span> on platforms that support :ctype:`long long`.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_480">480</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_481">481</td><td nowrap="nowrap"> ``K`` (long) [unsigned PY_LONG_LONG]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__64">n</a></td><td class="diff_header" id="from3_482">482-</td><td nowrap="nowrap"> Convert a C :ctype:`unsigned long long` to a Python long integer object.<span class="diff_sub"> Only</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__64">n</a></td><td class="diff_header" id="to3_497">497+</td><td nowrap="nowrap"> Convert a C :ctype:`unsigned long long` to a Python long integer object.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__64"></td><td class="diff_header" id="from3_483">483-</td><td nowrap="nowrap"> available on platforms that support :ctype:`unsigned long long`.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__64"></td><td class="diff_header" id="to3_498">498+</td><td nowrap="nowrap"> <span class="diff_add"> Only</span> available on platforms that support :ctype:`unsigned long long`.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_484">484</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_485">485</td><td nowrap="nowrap"> ``n`` (int) [Py_ssize_t]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_486">486</td><td nowrap="nowrap"> Convert a C :ctype:`Py_ssize_t` to a Python integer or long integer.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_487">487</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_488">488</td><td nowrap="nowrap"> .. versionadded:: 2.5</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_489">489</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_490">490</td><td nowrap="nowrap"> ``c`` (string of length 1) [char]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__65">n</a></td><td class="diff_header" id="from3_491">491-</td><td nowrap="nowrap"> Convert a C :ctype:`int` representing a character to a Python string of<span class="diff_sub"> length</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__65">n</a></td><td class="diff_header" id="to3_506">506+</td><td nowrap="nowrap"> Convert a C :ctype:`int` representing a character to a Python string of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_492">492-</td><td nowrap="nowrap"><span class="diff_sub"> 1.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_507">507+</td><td nowrap="nowrap"><span class="diff_add"> length 1.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_493">493</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_494">494</td><td nowrap="nowrap"> ``d`` (float) [double]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_495">495</td><td nowrap="nowrap"> Convert a C :ctype:`double` to a Python floating point number.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_496">496</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to3__65"></td><td class="diff_header" id="from3_497">497</td><td nowrap="nowrap"> ``f`` (float) [float]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_498">498</td><td nowrap="nowrap"> Same as ``d``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_499">499</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_500">500</td><td nowrap="nowrap"> ``D`` (complex) [Py_complex \*]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_501">501</td><td nowrap="nowrap"> Convert a C :ctype:`Py_complex` structure to a Python complex number.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_502">502</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_503">503</td><td nowrap="nowrap"> ``O`` (object) [PyObject \*]</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_504">504</td><td nowrap="nowrap"> Pass a Python object untouched (except for its reference count, which is</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__66">n</a></td><td class="diff_header" id="from3_505">505-</td><td nowrap="nowrap"> incremented by one). If the object passed in is a *NULL* pointer, it is<span class="diff_sub"> assumed</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__66">n</a></td><td class="diff_header" id="to3_520">520+</td><td nowrap="nowrap"> incremented by one). If the object passed in is a *NULL* pointer, it is</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_506">506-</td><td nowrap="nowrap"> that this was caused because the call producing the argument<span class="diff_sub"> found an error and</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_521">521+</td><td nowrap="nowrap"> <span class="diff_add"> assumed</span> that this was caused because the call producing the argument</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__66"></td><td class="diff_header" id="from3_507">507-</td><td nowrap="nowrap"><span class="diff_sub"> set an exception. Therefore, :cfunc:`Py_BuildValue` will return *NULL* but won't</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__66"></td><td class="diff_header" id="to3_522">522+</td><td nowrap="nowrap"><span class="diff_add"> found an error and set an exception. Therefore, :cfunc:`Py_BuildValue`</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_508">508-</td><td nowrap="nowrap"><span class="diff_sub"> raise an exception. If no exception has been raised yet, :exc:`SystemError` is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_523">523+</td><td nowrap="nowrap"><span class="diff_add"> will return *NULL* but won't raise an exception. If no exception has</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_509">509-</td><td nowrap="nowrap"><span class="diff_sub"> set.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_524">524+</td><td nowrap="nowrap"><span class="diff_add"> been raised yet, :exc:`SystemError` is set.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_510">510</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_511">511</td><td nowrap="nowrap"> ``S`` (object) [PyObject \*]</td></tr> <tr><td class="diff_next" id="difflib_chg_to3__67"></td><td class="diff_header" id="from3_512">512</td><td nowrap="nowrap"> Same as ``O``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_513">513</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_514">514</td><td nowrap="nowrap"> ``N`` (object) [PyObject \*]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__67">n</a></td><td class="diff_header" id="from3_515">515-</td><td nowrap="nowrap"> Same as ``O``, except it doesn't increment the reference count on the<span class="diff_sub"> object.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__67">n</a></td><td class="diff_header" id="to3_530">530+</td><td nowrap="nowrap"> Same as ``O``, except it doesn't increment the reference count on the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_516">516-</td><td nowrap="nowrap"> Useful when the object is created by a call to an object<span class="diff_sub"> constructor in the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_531">531+</td><td nowrap="nowrap"> <span class="diff_add"> object.</span> Useful when the object is created by a call to an object</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_517">517-</td><td nowrap="nowrap"><span class="diff_sub"> argument list.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_532">532+</td><td nowrap="nowrap"><span class="diff_add"> constructor in the argument list.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to3__68"></td><td class="diff_header" id="from3_518">518</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_519">519</td><td nowrap="nowrap"> ``O&`` (object) [*converter*, *anything*]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__68">n</a></td><td class="diff_header" id="from3_520">520-</td><td nowrap="nowrap"> Convert *anything* to a Python object through a *converter* function.<span class="diff_sub"> The</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__68">n</a></td><td class="diff_header" id="to3_535">535+</td><td nowrap="nowrap"> Convert *anything* to a Python object through a *converter* function.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_521">521-</td><td nowrap="nowrap"> function is called with *anything* (which should be compatible with<span class="diff_sub"> :ctype:`void</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_536">536+</td><td nowrap="nowrap"> <span class="diff_add"> The</span> function is called with *anything* (which should be compatible with</td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__69"></td><td class="diff_header" id="from3_522">522-</td><td nowrap="nowrap"> \*`) as its argument and should return a "new" Python<span class="diff_sub"> object, or *NULL* if an</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__69"></td><td class="diff_header" id="to3_537">537+</td><td nowrap="nowrap"> <span class="diff_add"> :ctype:`void</span> \*`) as its argument and should return a "new" Python</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_523">523-</td><td nowrap="nowrap"><span class="diff_sub"> error occurred.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_538">538+</td><td nowrap="nowrap"><span class="diff_add"> object, or *NULL* if an error occurred.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_524">524</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_525">525</td><td nowrap="nowrap"> ``(items)`` (tuple) [*matching-items*]</td></tr><tr><td class="diff_next" id="difflib_chg_to3__70"><a href="#difflib_chg_to3__69">n</a></td><td class="diff_header" id="from3_526">526-</td><td nowrap="nowrap"> Convert a sequence of C values to a Python tuple with the same number of<span class="diff_sub"> items.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__70"><a href="#difflib_chg_to3__69">n</a></td><td class="diff_header" id="to3_541">541+</td><td nowrap="nowrap"> Convert a sequence of C values to a Python tuple with the same number of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_542">542+</td><td nowrap="nowrap"><span class="diff_add"> items.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_527">527</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_528">528</td><td nowrap="nowrap"> ``[items]`` (list) [*matching-items*]</td></tr><tr><td class="diff_next" id="difflib_chg_to3__71"><a href="#difflib_chg_to3__70">n</a></td><td class="diff_header" id="from3_529">529-</td><td nowrap="nowrap"> Convert a sequence of C values to a Python list with the same number of<span class="diff_sub"> items.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to3__71"><a href="#difflib_chg_to3__70">n</a></td><td class="diff_header" id="to3_545">545+</td><td nowrap="nowrap"> Convert a sequence of C values to a Python list with the same number of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_546">546+</td><td nowrap="nowrap"><span class="diff_add"> items.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_530">530</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_531">531</td><td nowrap="nowrap"> ``{items}`` (dictionary) [*matching-items*]</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__71">n</a></td><td class="diff_header" id="from3_532">532-</td><td nowrap="nowrap"> Convert a sequence of C values to a Python dictionary. Each pair of<span class="diff_sub"> consecutive</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__71">n</a></td><td class="diff_header" id="to3_549">549+</td><td nowrap="nowrap"> Convert a sequence of C values to a Python dictionary. Each pair of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_533">533-</td><td nowrap="nowrap"> C values adds one item to the dictionary, serving as key and<span class="diff_sub"> value,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_550">550+</td><td nowrap="nowrap"> <span class="diff_add"> consecutive</span> C values adds one item to the dictionary, serving as key and</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_534">534-</td><td nowrap="nowrap"> respectively.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_551">551+</td><td nowrap="nowrap"> <span class="diff_add"> value,</span> respectively.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_535">535</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to3__top">t</a></td><td class="diff_header" id="from3_536">536-</td><td nowrap="nowrap"> If there is an error in the format string, the :exc:`SystemError` exception<span class="diff_sub"> is</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to3__top">t</a></td><td class="diff_header" id="to3_553">553+</td><td nowrap="nowrap"> If there is an error in the format string, the :exc:`SystemError` exception</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from3_537">537-</td><td nowrap="nowrap"> set and *NULL* returned.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to3_554">554+</td><td nowrap="nowrap"> <span class="diff_add"> is</span> set and *NULL* returned.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from3_538">538</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_539">539</td><td nowrap="nowrap">.. cfunction:: PyObject* Py_VaBuildValue(const char *format, va_list vargs)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_540">540</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_541">541</td><td nowrap="nowrap"> Identical to :cfunc:`Py_BuildValue`, except that it accepts a va_list</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from3_542">542</td><td nowrap="nowrap"> rather than a variable number of arguments.</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/buffer.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,455 @@ +--- r262/c-api/buffer.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/buffer.rst 2010-03-22 04:06:51.755104000 +0900 +@@ -4,116 +4,416 @@ + + Buffer Objects + -------------- + + .. sectionauthor:: Greg Stein <gstei****@lyra*****> + + + .. index:: + object: buffer + single: buffer interface + + Python objects implemented in C can export a group of functions called the +-"buffer interface." These functions can be used by an object to expose its data +-in a raw, byte-oriented format. Clients of the object can use the buffer +-interface to access the object data directly, without needing to copy it first. ++"buffer interface." These functions can be used by an object to expose its ++data in a raw, byte-oriented format. Clients of the object can use the buffer ++interface to access the object data directly, without needing to copy it ++first. + + Two examples of objects that support the buffer interface are strings and + arrays. The string object exposes the character contents in the buffer + interface's byte-oriented form. An array can also expose its contents, but it + should be noted that array elements may be multi-byte values. + + An example user of the buffer interface is the file object's :meth:`write` + method. Any object that can export a series of bytes through the buffer + interface can be written to a file. There are a number of format codes to + :cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface, + returning data from the target object. + ++Starting from version 1.6, Python has been providing Python-level buffer ++objects and a C-level buffer API so that any built-in or used-defined type can ++expose its characteristics. Both, however, have been deprecated because of ++various shortcomings, and have been officially removed in Python 3.0 in favour ++of a new C-level buffer API and a new Python-level object named ++:class:`memoryview`. ++ ++The new buffer API has been backported to Python 2.6, and the ++:class:`memoryview` object has been backported to Python 2.7. It is strongly ++advised to use them rather than the old APIs, unless you are blocked from ++doing so for compatibility reasons. ++ ++ ++The new-style Py_buffer struct ++============================== ++ ++ ++.. ctype:: Py_buffer ++ ++ .. cmember:: void *buf ++ ++ A pointer to the start of the memory for the object. ++ ++ .. cmember:: Py_ssize_t len ++ :noindex: ++ ++ The total length of the memory in bytes. ++ ++ .. cmember:: int readonly ++ ++ An indicator of whether the buffer is read only. ++ ++ .. cmember:: const char *format ++ :noindex: ++ ++ A *NULL* terminated string in :mod:`struct` module style syntax giving ++ the contents of the elements available through the buffer. If this is ++ *NULL*, ``"B"`` (unsigned bytes) is assumed. ++ ++ .. cmember:: int ndim ++ ++ The number of dimensions the memory represents as a multi-dimensional ++ array. If it is 0, :cdata:`strides` and :cdata:`suboffsets` must be ++ *NULL*. ++ ++ .. cmember:: Py_ssize_t *shape ++ ++ An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the ++ shape of the memory as a multi-dimensional array. Note that ++ ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to ++ :cdata:`len`. ++ ++ .. cmember:: Py_ssize_t *strides ++ ++ An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the ++ number of bytes to skip to get to a new element in each dimension. ++ ++ .. cmember:: Py_ssize_t *suboffsets ++ ++ An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim`. If these ++ suboffset numbers are greater than or equal to 0, then the value stored ++ along the indicated dimension is a pointer and the suboffset value ++ dictates how many bytes to add to the pointer after de-referencing. A ++ suboffset value that it negative indicates that no de-referencing should ++ occur (striding in a contiguous memory block). ++ ++ Here is a function that returns a pointer to the element in an N-D array ++ pointed to by an N-dimesional index when there are both non-NULL strides ++ and suboffsets:: ++ ++ void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides, ++ Py_ssize_t *suboffsets, Py_ssize_t *indices) { ++ char *pointer = (char*)buf; ++ int i; ++ for (i = 0; i < ndim; i++) { ++ pointer += strides[i] * indices[i]; ++ if (suboffsets[i] >=0 ) { ++ pointer = *((char**)pointer) + suboffsets[i]; ++ } ++ } ++ return (void*)pointer; ++ } ++ ++ ++ .. cmember:: Py_ssize_t itemsize ++ ++ This is a storage for the itemsize (in bytes) of each element of the ++ shared memory. It is technically un-necessary as it can be obtained ++ using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know ++ this information without parsing the format string and it is necessary ++ to know the itemsize for proper interpretation of striding. Therefore, ++ storing it is more convenient and faster. ++ ++ .. cmember:: void *internal ++ ++ This is for use internally by the exporting object. For example, this ++ might be re-cast as an integer by the exporter and used to store flags ++ about whether or not the shape, strides, and suboffsets arrays must be ++ freed when the buffer is released. The consumer should never alter this ++ value. ++ ++ ++Buffer related functions ++======================== ++ ++ ++.. cfunction:: int PyObject_CheckBuffer(PyObject *obj) ++ ++ Return 1 if *obj* supports the buffer interface otherwise 0. ++ ++ ++.. cfunction:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags) ++ ++ Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must ++ never be *NULL*. The *flags* argument is a bit field indicating what ++ kind of buffer the caller is prepared to deal with and therefore what ++ kind of buffer the exporter is allowed to return. The buffer interface ++ allows for complicated memory sharing possibilities, but some caller may ++ not be able to handle all the complexity but may want to see if the ++ exporter will let them take a simpler view to its memory. ++ ++ Some exporters may not be able to share memory in every possible way and ++ may need to raise errors to signal to some consumers that something is ++ just not possible. These errors should be a :exc:`BufferError` unless ++ there is another error that is actually causing the problem. The ++ exporter can use flags information to simplify how much of the ++ :cdata:`Py_buffer` structure is filled in with non-default values and/or ++ raise an error if the object can't support a simpler view of its memory. ++ ++ 0 is returned on success and -1 on error. ++ ++ The following table gives possible values to the *flags* arguments. ++ ++ +------------------------------+---------------------------------------------------+ ++ | Flag | Description | ++ +==============================+===================================================+ ++ | :cmacro:`PyBUF_SIMPLE` | This is the default flag state. The returned | ++ | | buffer may or may not have writable memory. The | ++ | | format of the data will be assumed to be unsigned | ++ | | bytes. This is a "stand-alone" flag constant. It | ++ | | never needs to be '|'d to the others. The exporter| ++ | | will raise an error if it cannot provide such a | ++ | | contiguous buffer of bytes. | ++ | | | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is | ++ | | not writable, then raise an error. | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_STRIDES` | This implies :cmacro:`PyBUF_ND`. The returned | ++ | | buffer must provide strides information (i.e. the | ++ | | strides cannot be NULL). This would be used when | ++ | | the consumer can handle strided, discontiguous | ++ | | arrays. Handling strides automatically assumes | ++ | | you can handle shape. The exporter can raise an | ++ | | error if a strided representation of the data is | ++ | | not possible (i.e. without the suboffsets). | ++ | | | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_ND` | The returned buffer must provide shape | ++ | | information. The memory will be assumed C-style | ++ | | contiguous (last dimension varies the | ++ | | fastest). The exporter may raise an error if it | ++ | | cannot provide this kind of contiguous buffer. If | ++ | | this is not given then shape will be *NULL*. | ++ | | | ++ | | | ++ | | | ++ +------------------------------+---------------------------------------------------+ ++ |:cmacro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned | ++ |:cmacro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last | ++ |:cmacro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous | ++ | | (first dimension varies the fastest) or either | ++ | | one. All of these flags imply | ++ | | :cmacro:`PyBUF_STRIDES` and guarantee that the | ++ | | strides buffer info structure will be filled in | ++ | | correctly. | ++ | | | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have | ++ | | suboffsets information (which can be NULL if no | ++ | | suboffsets are needed). This can be used when | ++ | | the consumer can handle indirect array | ++ | | referencing implied by these suboffsets. This | ++ | | implies :cmacro:`PyBUF_STRIDES`. | ++ | | | ++ | | | ++ | | | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_FORMAT` | The returned buffer must have true format | ++ | | information if this flag is provided. This would | ++ | | be used when the consumer is going to be checking | ++ | | for what 'kind' of data is actually stored. An | ++ | | exporter should always be able to provide this | ++ | | information if requested. If format is not | ++ | | explicitly requested then the format must be | ++ | | returned as *NULL* (which means ``'B'``, or | ++ | | unsigned bytes) | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | | ++ | | PyBUF_WRITABLE)``. | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. | ++ | | | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | | ++ | | PyBUF_FORMAT | PyBUF_WRITABLE)``. | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | | ++ | | PyBUF_FORMAT)``. | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | | ++ | | PyBUF_FORMAT | PyBUF_WRITABLE)``. | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | | ++ | | PyBUF_FORMAT)``. | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | | ++ | | PyBUF_WRITABLE)``. | ++ +------------------------------+---------------------------------------------------+ ++ | :cmacro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. | ++ | | | ++ +------------------------------+---------------------------------------------------+ ++ ++ ++.. cfunction:: void PyBuffer_Release(Py_buffer *view) ++ ++ Release the buffer *view*. This should be called when the buffer ++ is no longer being used as it may free memory from it. ++ ++ ++.. cfunction:: Py_ssize_t PyBuffer_SizeFromFormat(const char *) ++ ++ Return the implied :cdata:`~Py_buffer.itemsize` from the struct-stype ++ :cdata:`~Py_buffer.format`. ++ ++ ++.. cfunction:: int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len, char fortran) ++ ++ Copy *len* bytes of data pointed to by the contiguous chunk of memory ++ pointed to by *buf* into the buffer exported by obj. The buffer must of ++ course be writable. Return 0 on success and return -1 and raise an error ++ on failure. If the object does not have a writable buffer, then an error ++ is raised. If *fortran* is ``'F'``, then if the object is ++ multi-dimensional, then the data will be copied into the array in ++ Fortran-style (first dimension varies the fastest). If *fortran* is ++ ``'C'``, then the data will be copied into the array in C-style (last ++ dimension varies the fastest). If *fortran* is ``'A'``, then it does not ++ matter and the copy will be made in whatever way is more efficient. ++ ++ ++.. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran) ++ ++ Return 1 if the memory defined by the *view* is C-style (*fortran* is ++ ``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one ++ (*fortran* is ``'A'``). Return 0 otherwise. ++ ++ ++.. cfunction:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran) ++ ++ Fill the *strides* array with byte-strides of a contiguous (C-style if ++ *fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'`` array of the ++ given shape with the given number of bytes per element. ++ ++ ++.. cfunction:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags) ++ ++ Fill in a buffer-info structure, *view*, correctly for an exporter that can ++ only share a contiguous chunk of memory of "unsigned bytes" of the given ++ length. Return 0 on success and -1 (with raising an error) on error. ++ ++ ++Old-style buffer objects ++======================== ++ + .. index:: single: PyBufferProcs + + More information on the buffer interface is provided in the section + :ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`. + + A "buffer object" is defined in the :file:`bufferobject.h` header (included by + :file:`Python.h`). These objects look very similar to string objects at the + Python programming level: they support slicing, indexing, concatenation, and +-some other standard string operations. However, their data can come from one of +-two sources: from a block of memory, or from another object which exports the +-buffer interface. ++some other standard string operations. However, their data can come from one ++of two sources: from a block of memory, or from another object which exports ++the buffer interface. + + Buffer objects are useful as a way to expose the data from another object's +-buffer interface to the Python programmer. They can also be used as a zero-copy +-slicing mechanism. Using their ability to reference a block of memory, it is +-possible to expose any data to the Python programmer quite easily. The memory +-could be a large, constant array in a C extension, it could be a raw block of +-memory for manipulation before passing to an operating system library, or it +-could be used to pass around structured data in its native, in-memory format. ++buffer interface to the Python programmer. They can also be used as a ++zero-copy slicing mechanism. Using their ability to reference a block of ++memory, it is possible to expose any data to the Python programmer quite ++easily. The memory could be a large, constant array in a C extension, it could ++be a raw block of memory for manipulation before passing to an operating ++system library, or it could be used to pass around structured data in its ++native, in-memory format. + + + .. ctype:: PyBufferObject + + This subtype of :ctype:`PyObject` represents a buffer object. + + + .. cvar:: PyTypeObject PyBuffer_Type + + .. index:: single: BufferType (in module types) + + The instance of :ctype:`PyTypeObject` which represents the Python buffer type; + it is the same object as ``buffer`` and ``types.BufferType`` in the Python + layer. . + + + .. cvar:: int Py_END_OF_BUFFER + + This constant may be passed as the *size* parameter to + :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It +- indicates that the new :ctype:`PyBufferObject` should refer to *base* object +- from the specified *offset* to the end of its exported buffer. Using this +- enables the caller to avoid querying the *base* object for its length. ++ indicates that the new :ctype:`PyBufferObject` should refer to *base* ++ object from the specified *offset* to the end of its exported buffer. ++ Using this enables the caller to avoid querying the *base* object for its ++ length. + + + .. cfunction:: int PyBuffer_Check(PyObject *p) + + Return true if the argument has type :cdata:`PyBuffer_Type`. + + + .. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) + +- Return a new read-only buffer object. This raises :exc:`TypeError` if *base* +- doesn't support the read-only buffer protocol or doesn't provide exactly one +- buffer segment, or it raises :exc:`ValueError` if *offset* is less than zero. +- The buffer will hold a reference to the *base* object, and the buffer's contents +- will refer to the *base* object's buffer interface, starting as position +- *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`, +- then the new buffer's contents extend to the length of the *base* object's +- exported buffer data. ++ Return a new read-only buffer object. This raises :exc:`TypeError` if ++ *base* doesn't support the read-only buffer protocol or doesn't provide ++ exactly one buffer segment, or it raises :exc:`ValueError` if *offset* is ++ less than zero. The buffer will hold a reference to the *base* object, and ++ the buffer's contents will refer to the *base* object's buffer interface, ++ starting as position *offset* and extending for *size* bytes. If *size* is ++ :const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the ++ length of the *base* object's exported buffer data. ++ ++ .. versionchanged:: 2.5 ++ This function used an :ctype:`int` type for *offset* and *size*. This ++ might require changes in your code for properly supporting 64-bit ++ systems. + + + .. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size) + +- Return a new writable buffer object. Parameters and exceptions are similar to +- those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not export +- the writeable buffer protocol, then :exc:`TypeError` is raised. ++ Return a new writable buffer object. Parameters and exceptions are similar ++ to those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not ++ export the writeable buffer protocol, then :exc:`TypeError` is raised. ++ ++ .. versionchanged:: 2.5 ++ This function used an :ctype:`int` type for *offset* and *size*. This ++ might require changes in your code for properly supporting 64-bit ++ systems. + + + .. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size) + +- Return a new read-only buffer object that reads from a specified location in +- memory, with a specified size. The caller is responsible for ensuring that the +- memory buffer, passed in as *ptr*, is not deallocated while the returned buffer +- object exists. Raises :exc:`ValueError` if *size* is less than zero. Note that +- :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter; +- :exc:`ValueError` will be raised in that case. ++ Return a new read-only buffer object that reads from a specified location ++ in memory, with a specified size. The caller is responsible for ensuring ++ that the memory buffer, passed in as *ptr*, is not deallocated while the ++ returned buffer object exists. Raises :exc:`ValueError` if *size* is less ++ than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the ++ *size* parameter; :exc:`ValueError` will be raised in that case. ++ ++ .. 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* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size) + +- Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is writable. ++ Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is ++ writable. ++ ++ .. 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* PyBuffer_New(Py_ssize_t size) + + Return a new writable buffer object that maintains its own memory buffer of +- *size* bytes. :exc:`ValueError` is returned if *size* is not zero or positive. +- Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is +- not specifically aligned. ++ *size* bytes. :exc:`ValueError` is returned if *size* is not zero or ++ positive. Note that the memory buffer (as returned by ++ :cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned. ++ ++ .. 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. ======================================= --- /dev/null +++ /c-api/diff/buffer.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,422 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to4__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/buffer.rst => r266/c-api/buffer.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to4__0"></td><td class="diff_header" id="from4_8">8</td><td nowrap="nowrap">.. sectionauthor:: Greg Stein <gstei****@lyra*****></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_9">9</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_10">10</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_11">11</td><td nowrap="nowrap">.. index::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_12">12</td><td nowrap="nowrap"> object: buffer</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_13">13</td><td nowrap="nowrap"> single: buffer interface</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_14">14</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_15">15</td><td nowrap="nowrap">Python objects implemented in C can export a group of functions called the</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__1">n</a></td><td class="diff_header" id="from4_16">16-</td><td nowrap="nowrap">"buffer interface." These functions can be used by an object to expose its<span class="diff_sub"> data</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to4__1">n</a></td><td class="diff_header" id="to4_16">16+</td><td nowrap="nowrap">"buffer interface." These functions can be used by an object to expose its</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_17">17-</td><td nowrap="nowrap">in a raw, byte-oriented format. Clients of the object can use the buffer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_17">17+</td><td nowrap="nowrap"><span class="diff_add">data </span>in a raw, byte-oriented format. Clients of the object can use the buffer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_18">18-</td><td nowrap="nowrap">interface to access the object data directly, without needing to copy it<span class="diff_sub"> first.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_18">18+</td><td nowrap="nowrap">interface to access the object data directly, without needing to copy it</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_19">19+</td><td nowrap="nowrap"><span class="diff_add">first.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from4_19">19</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_20">20</td><td nowrap="nowrap">Two examples of objects that support the buffer interface are strings and</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_21">21</td><td nowrap="nowrap">arrays. The string object exposes the character contents in the buffer</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_22">22</td><td nowrap="nowrap">interface's byte-oriented form. An array can also expose its contents, but it</td></tr> <tr><td class="diff_next" id="difflib_chg_to4__1"></td><td class="diff_header" id="from4_23">23</td><td nowrap="nowrap">should be noted that array elements may be multi-byte values.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_24">24</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_25">25</td><td nowrap="nowrap">An example user of the buffer interface is the file object's :meth:`write`</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_26">26</td><td nowrap="nowrap">method. Any object that can export a series of bytes through the buffer</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_27">27</td><td nowrap="nowrap">interface can be written to a file. There are a number of format codes to</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_28">28</td><td nowrap="nowrap">:cfunc:`PyArg_ParseTuple` that operate against an object's buffer interface,</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_29">29</td><td nowrap="nowrap">returning data from the target object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_30">30</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__2">n</a></td><td class="diff_header" id="to4_32">32+</td><td nowrap="nowrap"><span class="diff_add">Starting from version 1.6, Python has been providing Python-level buffer</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_33">33+</td><td nowrap="nowrap"><span class="diff_add">objects and a C-level buffer API so that any built-in or used-defined type can</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_34">34+</td><td nowrap="nowrap"><span class="diff_add">expose its characteristics. Both, however, have been deprecated because of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_35">35+</td><td nowrap="nowrap"><span class="diff_add">various shortcomings, and have been officially removed in Python 3.0 in favour</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_36">36+</td><td nowrap="nowrap"><span class="diff_add">of a new C-level buffer API and a new Python-level object named</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_37">37+</td><td nowrap="nowrap"><span class="diff_add">:class:`memoryview`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_38">38+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_39">39+</td><td nowrap="nowrap"><span class="diff_add">The new buffer API has been backported to Python 2.6, and the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_40">40+</td><td nowrap="nowrap"><span class="diff_add">:class:`memoryview` object has been backported to Python 2.7. It is strongly</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_41">41+</td><td nowrap="nowrap"><span class="diff_add">advised to use them rather than the old APIs, unless you are blocked from</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_42">42+</td><td nowrap="nowrap"><span class="diff_add">doing so for compatibility reasons.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_43">43+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_44">44+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_45">45+</td><td nowrap="nowrap"><span class="diff_add">The new-style Py_buffer struct</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_46">46+</td><td nowrap="nowrap"><span class="diff_add">==============================</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_47">47+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_48">48+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_49">49+</td><td nowrap="nowrap"><span class="diff_add">.. ctype:: Py_buffer</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_50">50+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_51">51+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: void *buf</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_52">52+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_53">53+</td><td nowrap="nowrap"><span class="diff_add"> A pointer to the start of the memory for the object.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_54">54+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_55">55+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: Py_ssize_t len</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_56">56+</td><td nowrap="nowrap"><span class="diff_add"> :noindex:</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_57">57+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_58">58+</td><td nowrap="nowrap"><span class="diff_add"> The total length of the memory in bytes.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_59">59+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_60">60+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: int readonly</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_61">61+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_62">62+</td><td nowrap="nowrap"><span class="diff_add"> An indicator of whether the buffer is read only.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_63">63+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_64">64+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: const char *format</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_65">65+</td><td nowrap="nowrap"><span class="diff_add"> :noindex:</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_66">66+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_67">67+</td><td nowrap="nowrap"><span class="diff_add"> A *NULL* terminated string in :mod:`struct` module style syntax giving</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_68">68+</td><td nowrap="nowrap"><span class="diff_add"> the contents of the elements available through the buffer. If this is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_69">69+</td><td nowrap="nowrap"><span class="diff_add"> *NULL*, ``"B"`` (unsigned bytes) is assumed.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_70">70+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_71">71+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: int ndim</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_72">72+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_73">73+</td><td nowrap="nowrap"><span class="diff_add"> The number of dimensions the memory represents as a multi-dimensional</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_74">74+</td><td nowrap="nowrap"><span class="diff_add"> array. If it is 0, :cdata:`strides` and :cdata:`suboffsets` must be</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_75">75+</td><td nowrap="nowrap"><span class="diff_add"> *NULL*.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_76">76+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_77">77+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: Py_ssize_t *shape</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_78">78+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_79">79+</td><td nowrap="nowrap"><span class="diff_add"> An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_80">80+</td><td nowrap="nowrap"><span class="diff_add"> shape of the memory as a multi-dimensional array. Note that</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_81">81+</td><td nowrap="nowrap"><span class="diff_add"> ``((*shape)[0] * ... * (*shape)[ndims-1])*itemsize`` should be equal to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_82">82+</td><td nowrap="nowrap"><span class="diff_add"> :cdata:`len`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_83">83+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_84">84+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: Py_ssize_t *strides</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_85">85+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_86">86+</td><td nowrap="nowrap"><span class="diff_add"> An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim` giving the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_87">87+</td><td nowrap="nowrap"><span class="diff_add"> number of bytes to skip to get to a new element in each dimension.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_88">88+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_89">89+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: Py_ssize_t *suboffsets</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_90">90+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_91">91+</td><td nowrap="nowrap"><span class="diff_add"> An array of :ctype:`Py_ssize_t`\s the length of :cdata:`ndim`. If these</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_92">92+</td><td nowrap="nowrap"><span class="diff_add"> suboffset numbers are greater than or equal to 0, then the value stored</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_93">93+</td><td nowrap="nowrap"><span class="diff_add"> along the indicated dimension is a pointer and the suboffset value</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_94">94+</td><td nowrap="nowrap"><span class="diff_add"> dictates how many bytes to add to the pointer after de-referencing. A</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_95">95+</td><td nowrap="nowrap"><span class="diff_add"> suboffset value that it negative indicates that no de-referencing should</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_96">96+</td><td nowrap="nowrap"><span class="diff_add"> occur (striding in a contiguous memory block).</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_97">97+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_98">98+</td><td nowrap="nowrap"><span class="diff_add"> Here is a function that returns a pointer to the element in an N-D array</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_99">99+</td><td nowrap="nowrap"><span class="diff_add"> pointed to by an N-dimesional index when there are both non-NULL strides</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_100">100+</td><td nowrap="nowrap"><span class="diff_add"> and suboffsets::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_101">101+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_102">102+</td><td nowrap="nowrap"><span class="diff_add"> void *get_item_pointer(int ndim, void *buf, Py_ssize_t *strides,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_103">103+</td><td nowrap="nowrap"><span class="diff_add"> Py_ssize_t *suboffsets, Py_ssize_t *indices) {</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_104">104+</td><td nowrap="nowrap"><span class="diff_add"> char *pointer = (char*)buf;</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_105">105+</td><td nowrap="nowrap"><span class="diff_add"> int i;</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_106">106+</td><td nowrap="nowrap"><span class="diff_add"> for (i = 0; i < ndim; i++) {</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_107">107+</td><td nowrap="nowrap"><span class="diff_add"> pointer += strides[i] * indices[i];</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_108">108+</td><td nowrap="nowrap"><span class="diff_add"> if (suboffsets[i] >=0 ) {</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_109">109+</td><td nowrap="nowrap"><span class="diff_add"> pointer = *((char**)pointer) + suboffsets[i];</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_110">110+</td><td nowrap="nowrap"><span class="diff_add"> }</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_111">111+</td><td nowrap="nowrap"><span class="diff_add"> }</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_112">112+</td><td nowrap="nowrap"><span class="diff_add"> return (void*)pointer;</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_113">113+</td><td nowrap="nowrap"><span class="diff_add"> }</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_114">114+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_115">115+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_116">116+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: Py_ssize_t itemsize</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_117">117+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_118">118+</td><td nowrap="nowrap"><span class="diff_add"> This is a storage for the itemsize (in bytes) of each element of the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_119">119+</td><td nowrap="nowrap"><span class="diff_add"> shared memory. It is technically un-necessary as it can be obtained</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_120">120+</td><td nowrap="nowrap"><span class="diff_add"> using :cfunc:`PyBuffer_SizeFromFormat`, however an exporter may know</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_121">121+</td><td nowrap="nowrap"><span class="diff_add"> this information without parsing the format string and it is necessary</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_122">122+</td><td nowrap="nowrap"><span class="diff_add"> to know the itemsize for proper interpretation of striding. Therefore,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_123">123+</td><td nowrap="nowrap"><span class="diff_add"> storing it is more convenient and faster.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_124">124+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_125">125+</td><td nowrap="nowrap"><span class="diff_add"> .. cmember:: void *internal</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_126">126+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_127">127+</td><td nowrap="nowrap"><span class="diff_add"> This is for use internally by the exporting object. For example, this</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_128">128+</td><td nowrap="nowrap"><span class="diff_add"> might be re-cast as an integer by the exporter and used to store flags</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_129">129+</td><td nowrap="nowrap"><span class="diff_add"> about whether or not the shape, strides, and suboffsets arrays must be</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_130">130+</td><td nowrap="nowrap"><span class="diff_add"> freed when the buffer is released. The consumer should never alter this</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_131">131+</td><td nowrap="nowrap"><span class="diff_add"> value.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_132">132+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_133">133+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_134">134+</td><td nowrap="nowrap"><span class="diff_add">Buffer related functions</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_135">135+</td><td nowrap="nowrap"><span class="diff_add">========================</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_136">136+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_137">137+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_138">138+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: int PyObject_CheckBuffer(PyObject *obj)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_139">139+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_140">140+</td><td nowrap="nowrap"><span class="diff_add"> Return 1 if *obj* supports the buffer interface otherwise 0.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_141">141+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_142">142+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_143">143+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: int PyObject_GetBuffer(PyObject *obj, Py_buffer *view, int flags)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_144">144+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_145">145+</td><td nowrap="nowrap"><span class="diff_add"> Export *obj* into a :ctype:`Py_buffer`, *view*. These arguments must</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_146">146+</td><td nowrap="nowrap"><span class="diff_add"> never be *NULL*. The *flags* argument is a bit field indicating what</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_147">147+</td><td nowrap="nowrap"><span class="diff_add"> kind of buffer the caller is prepared to deal with and therefore what</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_148">148+</td><td nowrap="nowrap"><span class="diff_add"> kind of buffer the exporter is allowed to return. The buffer interface</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_149">149+</td><td nowrap="nowrap"><span class="diff_add"> allows for complicated memory sharing possibilities, but some caller may</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_150">150+</td><td nowrap="nowrap"><span class="diff_add"> not be able to handle all the complexity but may want to see if the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_151">151+</td><td nowrap="nowrap"><span class="diff_add"> exporter will let them take a simpler view to its memory.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_152">152+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_153">153+</td><td nowrap="nowrap"><span class="diff_add"> Some exporters may not be able to share memory in every possible way and</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_154">154+</td><td nowrap="nowrap"><span class="diff_add"> may need to raise errors to signal to some consumers that something is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_155">155+</td><td nowrap="nowrap"><span class="diff_add"> just not possible. These errors should be a :exc:`BufferError` unless</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_156">156+</td><td nowrap="nowrap"><span class="diff_add"> there is another error that is actually causing the problem. The</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_157">157+</td><td nowrap="nowrap"><span class="diff_add"> exporter can use flags information to simplify how much of the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_158">158+</td><td nowrap="nowrap"><span class="diff_add"> :cdata:`Py_buffer` structure is filled in with non-default values and/or</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_159">159+</td><td nowrap="nowrap"><span class="diff_add"> raise an error if the object can't support a simpler view of its memory.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_160">160+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_161">161+</td><td nowrap="nowrap"><span class="diff_add"> 0 is returned on success and -1 on error.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_162">162+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_163">163+</td><td nowrap="nowrap"><span class="diff_add"> The following table gives possible values to the *flags* arguments.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_164">164+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_165">165+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_166">166+</td><td nowrap="nowrap"><span class="diff_add"> | Flag | Description | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_167">167+</td><td nowrap="nowrap"><span class="diff_add"> +==============================+===================================================+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_168">168+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_SIMPLE` | This is the default flag state. The returned | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_169">169+</td><td nowrap="nowrap"><span class="diff_add"> | | buffer may or may not have writable memory. The | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_170">170+</td><td nowrap="nowrap"><span class="diff_add"> | | format of the data will be assumed to be unsigned | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_171">171+</td><td nowrap="nowrap"><span class="diff_add"> | | bytes. This is a "stand-alone" flag constant. It | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_172">172+</td><td nowrap="nowrap"><span class="diff_add"> | | never needs to be '|'d to the others. The exporter| </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_173">173+</td><td nowrap="nowrap"><span class="diff_add"> | | will raise an error if it cannot provide such a | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_174">174+</td><td nowrap="nowrap"><span class="diff_add"> | | contiguous buffer of bytes. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_175">175+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_176">176+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_177">177+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_WRITABLE` | The returned buffer must be writable. If it is | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_178">178+</td><td nowrap="nowrap"><span class="diff_add"> | | not writable, then raise an error. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_179">179+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_180">180+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_STRIDES` | This implies :cmacro:`PyBUF_ND`. The returned | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_181">181+</td><td nowrap="nowrap"><span class="diff_add"> | | buffer must provide strides information (i.e. the | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_182">182+</td><td nowrap="nowrap"><span class="diff_add"> | | strides cannot be NULL). This would be used when | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_183">183+</td><td nowrap="nowrap"><span class="diff_add"> | | the consumer can handle strided, discontiguous | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_184">184+</td><td nowrap="nowrap"><span class="diff_add"> | | arrays. Handling strides automatically assumes | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_185">185+</td><td nowrap="nowrap"><span class="diff_add"> | | you can handle shape. The exporter can raise an | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_186">186+</td><td nowrap="nowrap"><span class="diff_add"> | | error if a strided representation of the data is | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_187">187+</td><td nowrap="nowrap"><span class="diff_add"> | | not possible (i.e. without the suboffsets). | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_188">188+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_189">189+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_190">190+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_ND` | The returned buffer must provide shape | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_191">191+</td><td nowrap="nowrap"><span class="diff_add"> | | information. The memory will be assumed C-style | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_192">192+</td><td nowrap="nowrap"><span class="diff_add"> | | contiguous (last dimension varies the | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_193">193+</td><td nowrap="nowrap"><span class="diff_add"> | | fastest). The exporter may raise an error if it | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_194">194+</td><td nowrap="nowrap"><span class="diff_add"> | | cannot provide this kind of contiguous buffer. If | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_195">195+</td><td nowrap="nowrap"><span class="diff_add"> | | this is not given then shape will be *NULL*. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_196">196+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_197">197+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_198">198+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_199">199+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_200">200+</td><td nowrap="nowrap"><span class="diff_add"> |:cmacro:`PyBUF_C_CONTIGUOUS` | These flags indicate that the contiguity returned | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_201">201+</td><td nowrap="nowrap"><span class="diff_add"> |:cmacro:`PyBUF_F_CONTIGUOUS` | buffer must be respectively, C-contiguous (last | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_202">202+</td><td nowrap="nowrap"><span class="diff_add"> |:cmacro:`PyBUF_ANY_CONTIGUOUS`| dimension varies the fastest), Fortran contiguous | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_203">203+</td><td nowrap="nowrap"><span class="diff_add"> | | (first dimension varies the fastest) or either | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_204">204+</td><td nowrap="nowrap"><span class="diff_add"> | | one. All of these flags imply | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_205">205+</td><td nowrap="nowrap"><span class="diff_add"> | | :cmacro:`PyBUF_STRIDES` and guarantee that the | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_206">206+</td><td nowrap="nowrap"><span class="diff_add"> | | strides buffer info structure will be filled in | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_207">207+</td><td nowrap="nowrap"><span class="diff_add"> | | correctly. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_208">208+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_209">209+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_210">210+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_INDIRECT` | This flag indicates the returned buffer must have | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_211">211+</td><td nowrap="nowrap"><span class="diff_add"> | | suboffsets information (which can be NULL if no | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_212">212+</td><td nowrap="nowrap"><span class="diff_add"> | | suboffsets are needed). This can be used when | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_213">213+</td><td nowrap="nowrap"><span class="diff_add"> | | the consumer can handle indirect array | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_214">214+</td><td nowrap="nowrap"><span class="diff_add"> | | referencing implied by these suboffsets. This | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_215">215+</td><td nowrap="nowrap"><span class="diff_add"> | | implies :cmacro:`PyBUF_STRIDES`. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_216">216+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_217">217+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_218">218+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_219">219+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_220">220+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_FORMAT` | The returned buffer must have true format | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_221">221+</td><td nowrap="nowrap"><span class="diff_add"> | | information if this flag is provided. This would | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_222">222+</td><td nowrap="nowrap"><span class="diff_add"> | | be used when the consumer is going to be checking | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_223">223+</td><td nowrap="nowrap"><span class="diff_add"> | | for what 'kind' of data is actually stored. An | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_224">224+</td><td nowrap="nowrap"><span class="diff_add"> | | exporter should always be able to provide this | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_225">225+</td><td nowrap="nowrap"><span class="diff_add"> | | information if requested. If format is not | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_226">226+</td><td nowrap="nowrap"><span class="diff_add"> | | explicitly requested then the format must be | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_227">227+</td><td nowrap="nowrap"><span class="diff_add"> | | returned as *NULL* (which means ``'B'``, or | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_228">228+</td><td nowrap="nowrap"><span class="diff_add"> | | unsigned bytes) | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_229">229+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_230">230+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_STRIDED` | This is equivalent to ``(PyBUF_STRIDES | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_231">231+</td><td nowrap="nowrap"><span class="diff_add"> | | PyBUF_WRITABLE)``. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_232">232+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_233">233+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_STRIDED_RO` | This is equivalent to ``(PyBUF_STRIDES)``. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_234">234+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_235">235+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_236">236+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_RECORDS` | This is equivalent to ``(PyBUF_STRIDES | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_237">237+</td><td nowrap="nowrap"><span class="diff_add"> | | PyBUF_FORMAT | PyBUF_WRITABLE)``. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_238">238+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_239">239+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_RECORDS_RO` | This is equivalent to ``(PyBUF_STRIDES | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_240">240+</td><td nowrap="nowrap"><span class="diff_add"> | | PyBUF_FORMAT)``. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_241">241+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_242">242+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_FULL` | This is equivalent to ``(PyBUF_INDIRECT | |</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_243">243+</td><td nowrap="nowrap"><span class="diff_add"> | | PyBUF_FORMAT | PyBUF_WRITABLE)``. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_244">244+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_245">245+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_FULL_RO` | This is equivalent to ``(PyBUF_INDIRECT | |</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_246">246+</td><td nowrap="nowrap"><span class="diff_add"> | | PyBUF_FORMAT)``. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_247">247+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_248">248+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_CONTIG` | This is equivalent to ``(PyBUF_ND | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_249">249+</td><td nowrap="nowrap"><span class="diff_add"> | | PyBUF_WRITABLE)``. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_250">250+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_251">251+</td><td nowrap="nowrap"><span class="diff_add"> | :cmacro:`PyBUF_CONTIG_RO` | This is equivalent to ``(PyBUF_ND)``. | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_252">252+</td><td nowrap="nowrap"><span class="diff_add"> | | | </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_253">253+</td><td nowrap="nowrap"><span class="diff_add"> +------------------------------+---------------------------------------------------+</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_254">254+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_255">255+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_256">256+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: void PyBuffer_Release(Py_buffer *view)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_257">257+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_258">258+</td><td nowrap="nowrap"><span class="diff_add"> Release the buffer *view*. This should be called when the buffer</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_259">259+</td><td nowrap="nowrap"><span class="diff_add"> is no longer being used as it may free memory from it.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_260">260+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_261">261+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_262">262+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: Py_ssize_t PyBuffer_SizeFromFormat(const char *)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_263">263+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_264">264+</td><td nowrap="nowrap"><span class="diff_add"> Return the implied :cdata:`~Py_buffer.itemsize` from the struct-stype</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_265">265+</td><td nowrap="nowrap"><span class="diff_add"> :cdata:`~Py_buffer.format`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_266">266+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_267">267+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_268">268+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: int PyObject_CopyToObject(PyObject *obj, void *buf, Py_ssize_t len, char fortran)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_269">269+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_270">270+</td><td nowrap="nowrap"><span class="diff_add"> Copy *len* bytes of data pointed to by the contiguous chunk of memory</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_271">271+</td><td nowrap="nowrap"><span class="diff_add"> pointed to by *buf* into the buffer exported by obj. The buffer must of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_272">272+</td><td nowrap="nowrap"><span class="diff_add"> course be writable. Return 0 on success and return -1 and raise an error</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_273">273+</td><td nowrap="nowrap"><span class="diff_add"> on failure. If the object does not have a writable buffer, then an error</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_274">274+</td><td nowrap="nowrap"><span class="diff_add"> is raised. If *fortran* is ``'F'``, then if the object is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_275">275+</td><td nowrap="nowrap"><span class="diff_add"> multi-dimensional, then the data will be copied into the array in</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_276">276+</td><td nowrap="nowrap"><span class="diff_add"> Fortran-style (first dimension varies the fastest). If *fortran* is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_277">277+</td><td nowrap="nowrap"><span class="diff_add"> ``'C'``, then the data will be copied into the array in C-style (last</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_278">278+</td><td nowrap="nowrap"><span class="diff_add"> dimension varies the fastest). If *fortran* is ``'A'``, then it does not</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_279">279+</td><td nowrap="nowrap"><span class="diff_add"> matter and the copy will be made in whatever way is more efficient.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_280">280+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_281">281+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_282">282+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: int PyBuffer_IsContiguous(Py_buffer *view, char fortran)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_283">283+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_284">284+</td><td nowrap="nowrap"><span class="diff_add"> Return 1 if the memory defined by the *view* is C-style (*fortran* is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_285">285+</td><td nowrap="nowrap"><span class="diff_add"> ``'C'``) or Fortran-style (*fortran* is ``'F'``) contiguous or either one</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_286">286+</td><td nowrap="nowrap"><span class="diff_add"> (*fortran* is ``'A'``). Return 0 otherwise.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_287">287+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_288">288+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_289">289+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: void PyBuffer_FillContiguousStrides(int ndim, Py_ssize_t *shape, Py_ssize_t *strides, Py_ssize_t itemsize, char fortran)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_290">290+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_291">291+</td><td nowrap="nowrap"><span class="diff_add"> Fill the *strides* array with byte-strides of a contiguous (C-style if</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_292">292+</td><td nowrap="nowrap"><span class="diff_add"> *fortran* is ``'C'`` or Fortran-style if *fortran* is ``'F'`` array of the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_293">293+</td><td nowrap="nowrap"><span class="diff_add"> given shape with the given number of bytes per element.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_294">294+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_295">295+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_296">296+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: int PyBuffer_FillInfo(Py_buffer *view, PyObject *obj, void *buf, Py_ssize_t len, int readonly, int infoflags)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_297">297+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_298">298+</td><td nowrap="nowrap"><span class="diff_add"> Fill in a buffer-info structure, *view*, correctly for an exporter that can</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_299">299+</td><td nowrap="nowrap"><span class="diff_add"> only share a contiguous chunk of memory of "unsigned bytes" of the given</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_300">300+</td><td nowrap="nowrap"><span class="diff_add"> length. Return 0 on success and -1 (with raising an error) on error.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_301">301+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_302">302+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_303">303+</td><td nowrap="nowrap"><span class="diff_add">Old-style buffer objects</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_304">304+</td><td nowrap="nowrap"><span class="diff_add">========================</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_305">305+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to4__2"></td><td class="diff_header" id="from4_31">31</td><td nowrap="nowrap">.. index:: single: PyBufferProcs</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_32">32</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_33">33</td><td nowrap="nowrap">More information on the buffer interface is provided in the section</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_34">34</td><td nowrap="nowrap">:ref:`buffer-structs`, under the description for :ctype:`PyBufferProcs`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_35">35</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to4__3"></td><td class="diff_header" id="from4_36">36</td><td nowrap="nowrap">A "buffer object" is defined in the :file:`bufferobject.h` header (included by</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_37">37</td><td nowrap="nowrap">:file:`Python.h`). These objects look very similar to string objects at the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_38">38</td><td nowrap="nowrap">Python programming level: they support slicing, indexing, concatenation, and</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__3">n</a></td><td class="diff_header" id="from4_39">39-</td><td nowrap="nowrap">some other standard string operations. However, their data can come from one<span class="diff_sub"> of</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to4__3">n</a></td><td class="diff_header" id="to4_314">314+</td><td nowrap="nowrap">some other standard string operations. However, their data can come from one</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_40">40-</td><td nowrap="nowrap">two sources: from a block of memory, or from another object which exports<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_315">315+</td><td nowrap="nowrap"><span class="diff_add">of </span>two sources: from a block of memory, or from another object which exports</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_41">41-</td><td nowrap="nowrap">buffer interface.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_316">316+</td><td nowrap="nowrap"><span class="diff_add">the </span>buffer interface.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from4_42">42</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_43">43</td><td nowrap="nowrap">Buffer objects are useful as a way to expose the data from another object's</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__4">n</a></td><td class="diff_header" id="from4_44">44-</td><td nowrap="nowrap">buffer interface to the Python programmer. They can also be used as a<span class="diff_sub"> zero-copy</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to4__4">n</a></td><td class="diff_header" id="to4_319">319+</td><td nowrap="nowrap">buffer interface to the Python programmer. They can also be used as a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_45">45-</td><td nowrap="nowrap">slicing mechanism. Using their ability to reference a block of<span class="diff_sub"> memory, it is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_320">320+</td><td nowrap="nowrap"><span class="diff_add">zero-copy </span>slicing mechanism. Using their ability to reference a block of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_46">46-</td><td nowrap="nowrap">possible to expose any data to the Python programmer quite<span class="diff_sub"> easily. The memory</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_321">321+</td><td nowrap="nowrap"><span class="diff_add">memory, it is </span>possible to expose any data to the Python programmer quite</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_47">47-</td><td nowrap="nowrap">could be a large, constant array in a C extension, it could<span class="diff_sub"> be a raw block of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_322">322+</td><td nowrap="nowrap"><span class="diff_add">easily. The memory </span>could be a large, constant array in a C extension, it could</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_48">48-</td><td nowrap="nowrap"><span class="diff_sub">memory for manipulation before passing to an operating system library, or it</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_323">323+</td><td nowrap="nowrap"><span class="diff_add">be a raw block of memory for manipulation before passing to an operating</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_49">49-</td><td nowrap="nowrap"><span class="diff_sub">could be used to pass around structured data in its native, in-memory format.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_324">324+</td><td nowrap="nowrap"><span class="diff_add">system library, or it could be used to pass around structured data in its</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_325">325+</td><td nowrap="nowrap"><span class="diff_add">native, in-memory format.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from4_50">50</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_51">51</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_52">52</td><td nowrap="nowrap">.. ctype:: PyBufferObject</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_53">53</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_54">54</td><td nowrap="nowrap"> This subtype of :ctype:`PyObject` represents a buffer object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_55">55</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_56">56</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_57">57</td><td nowrap="nowrap">.. cvar:: PyTypeObject PyBuffer_Type</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to4__4"></td><td class="diff_header" id="from4_62">62</td><td nowrap="nowrap"> it is the same object as ``buffer`` and ``types.BufferType`` in the Python</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_63">63</td><td nowrap="nowrap"> layer. .</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_64">64</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_65">65</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_66">66</td><td nowrap="nowrap">.. cvar:: int Py_END_OF_BUFFER</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_67">67</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_68">68</td><td nowrap="nowrap"> This constant may be passed as the *size* parameter to</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_69">69</td><td nowrap="nowrap"> :cfunc:`PyBuffer_FromObject` or :cfunc:`PyBuffer_FromReadWriteObject`. It</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__5">n</a></td><td class="diff_header" id="from4_70">70-</td><td nowrap="nowrap"> indicates that the new :ctype:`PyBufferObject` should refer to *base*<span class="diff_sub"> object</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to4__5">n</a></td><td class="diff_header" id="to4_346">346+</td><td nowrap="nowrap"> indicates that the new :ctype:`PyBufferObject` should refer to *base*</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_71">71-</td><td nowrap="nowrap"> from the specified *offset* to the end of its exported buffer.<span class="diff_sub"> Using this</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_347">347+</td><td nowrap="nowrap"> <span class="diff_add"> object</span> from the specified *offset* to the end of its exported buffer.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_72">72-</td><td nowrap="nowrap"> enables the caller to avoid querying the *base* object for its<span class="diff_sub"> length.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_348">348+</td><td nowrap="nowrap"> <span class="diff_add"> Using this</span> enables the caller to avoid querying the *base* object for its</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_349">349+</td><td nowrap="nowrap"><span class="diff_add"> length.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from4_73">73</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to4__5"></td><td class="diff_header" id="from4_74">74</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_75">75</td><td nowrap="nowrap">.. cfunction:: int PyBuffer_Check(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_76">76</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_77">77</td><td nowrap="nowrap"> Return true if the argument has type :cdata:`PyBuffer_Type`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_78">78</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_79">79</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_80">80</td><td nowrap="nowrap">.. cfunction:: PyObject* PyBuffer_FromObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_81">81</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__6">n</a></td><td class="diff_header" id="from4_82">82-</td><td nowrap="nowrap"> Return a new read-only buffer object. This raises :exc:`TypeError` if<span class="diff_sub"> *base*</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to4__6">n</a></td><td class="diff_header" id="to4_359">359+</td><td nowrap="nowrap"> Return a new read-only buffer object. This raises :exc:`TypeError` if</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_83">83-</td><td nowrap="nowrap"> doesn't support the read-only buffer protocol or doesn't provide<span class="diff_sub"> exactly one</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_360">360+</td><td nowrap="nowrap"> <span class="diff_add"> *base*</span> doesn't support the read-only buffer protocol or doesn't provide</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_84">84-</td><td nowrap="nowrap"> buffer segment, or it raises :exc:`ValueError` if *offset* is<span class="diff_sub"> less than zero.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_361">361+</td><td nowrap="nowrap"> <span class="diff_add"> exactly one</span> buffer segment, or it raises :exc:`ValueError` if *offset* is</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_85">85-</td><td nowrap="nowrap"> The buffer will hold a reference to the *base* object, and<span class="diff_sub"> the buffer's contents</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_362">362+</td><td nowrap="nowrap"> <span class="diff_add"> less than zero.</span> The buffer will hold a reference to the *base* object, and</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_86">86-</td><td nowrap="nowrap"><span class="diff_sub"> will refer to the *base* object's buffer interface, starting as position</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_363">363+</td><td nowrap="nowrap"><span class="diff_add"> the buffer's contents will refer to the *base* object's buffer interface,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_87">87-</td><td nowrap="nowrap"><span class="diff_sub"> *offset* and extending for *size* bytes. If *size* is :const:`Py_END_OF_BUFFER`,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_364">364+</td><td nowrap="nowrap"><span class="diff_add"> starting as position *offset* and extending for *size* bytes. If *size* is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_88">88-</td><td nowrap="nowrap"><span class="diff_sub"> then the new buffer's contents extend to the length of the *base* object's</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_365">365+</td><td nowrap="nowrap"><span class="diff_add"> :const:`Py_END_OF_BUFFER`, then the new buffer's contents extend to the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_89">89-</td><td nowrap="nowrap"><span class="diff_sub"> exported buffer data.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_366">366+</td><td nowrap="nowrap"><span class="diff_add"> length of the *base* object's exported buffer data.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_367">367+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to4__6"></td><td class="diff_header" id="to4_368">368+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_369">369+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *offset* and *size*. This</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_370">370+</td><td nowrap="nowrap"><span class="diff_add"> might require changes in your code for properly supporting 64-bit</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_371">371+</td><td nowrap="nowrap"><span class="diff_add"> systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from4_90">90</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_91">91</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_92">92</td><td nowrap="nowrap">.. cfunction:: PyObject* PyBuffer_FromReadWriteObject(PyObject *base, Py_ssize_t offset, Py_ssize_t size)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_93">93</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__7">n</a></td><td class="diff_header" id="from4_94">94-</td><td nowrap="nowrap"> Return a new writable buffer object. Parameters and exceptions are similar<span class="diff_sub"> to</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to4__7">n</a></td><td class="diff_header" id="to4_376">376+</td><td nowrap="nowrap"> Return a new writable buffer object. Parameters and exceptions are similar</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_95">95-</td><td nowrap="nowrap"> those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not<span class="diff_sub"> export</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_377">377+</td><td nowrap="nowrap"> <span class="diff_add"> to</span> those for :cfunc:`PyBuffer_FromObject`. If the *base* object does not</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_96">96-</td><td nowrap="nowrap"> the writeable buffer protocol, then :exc:`TypeError` is raised.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_378">378+</td><td nowrap="nowrap"> <span class="diff_add"> export</span> the writeable buffer protocol, then :exc:`TypeError` is raised.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_379">379+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to4__7"></td><td class="diff_header" id="to4_380">380+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_381">381+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *offset* and *size*. This</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_382">382+</td><td nowrap="nowrap"><span class="diff_add"> might require changes in your code for properly supporting 64-bit</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_383">383+</td><td nowrap="nowrap"><span class="diff_add"> systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from4_97">97</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_98">98</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_99">99</td><td nowrap="nowrap">.. cfunction:: PyObject* PyBuffer_FromMemory(void *ptr, Py_ssize_t size)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_100">100</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__8">n</a></td><td class="diff_header" id="from4_101">101-</td><td nowrap="nowrap"> Return a new read-only buffer object that reads from a specified location<span class="diff_sub"> in</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to4__8">n</a></td><td class="diff_header" id="to4_388">388+</td><td nowrap="nowrap"> Return a new read-only buffer object that reads from a specified location</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_102">102-</td><td nowrap="nowrap"> memory, with a specified size. The caller is responsible for ensuring<span class="diff_sub"> that the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_389">389+</td><td nowrap="nowrap"> <span class="diff_add"> in</span> memory, with a specified size. The caller is responsible for ensuring</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_103">103-</td><td nowrap="nowrap"> memory buffer, passed in as *ptr*, is not deallocated while the<span class="diff_sub"> returned buffer</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_390">390+</td><td nowrap="nowrap"> <span class="diff_add"> that the</span> memory buffer, passed in as *ptr*, is not deallocated while the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_104">104-</td><td nowrap="nowrap"> object exists. Raises :exc:`ValueError` if *size* is less<span class="diff_sub"> than zero. Note that</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_391">391+</td><td nowrap="nowrap"> <span class="diff_add"> returned buffer</span> object exists. Raises :exc:`ValueError` if *size* is less</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_105">105-</td><td nowrap="nowrap"><span class="diff_sub"> :const:`Py_END_OF_BUFFER` may *not* be passed for the *size* parameter;</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_392">392+</td><td nowrap="nowrap"><span class="diff_add"> than zero. Note that :const:`Py_END_OF_BUFFER` may *not* be passed for the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_106">106-</td><td nowrap="nowrap"> :exc:`ValueError` will be raised in that case.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_393">393+</td><td nowrap="nowrap"> <span class="diff_add"> *size* parameter;</span> :exc:`ValueError` will be raised in that case.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to4__8"></td><td class="diff_header" id="to4_394">394+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_395">395+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_396">396+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *size*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_397">397+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from4_107">107</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_108">108</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_109">109</td><td nowrap="nowrap">.. cfunction:: PyObject* PyBuffer_FromReadWriteMemory(void *ptr, Py_ssize_t size)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_110">110</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__9">n</a></td><td class="diff_header" id="from4_111">111-</td><td nowrap="nowrap"> Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is<span class="diff_sub"> writable.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to4__9">n</a></td><td class="diff_header" id="to4_402">402+</td><td nowrap="nowrap"> Similar to :cfunc:`PyBuffer_FromMemory`, but the returned buffer is</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_403">403+</td><td nowrap="nowrap"><span class="diff_add"> writable.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_404">404+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to4__9"></td><td class="diff_header" id="to4_405">405+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_406">406+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *size*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_407">407+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from4_112">112</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_113">113</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_114">114</td><td nowrap="nowrap">.. cfunction:: PyObject* PyBuffer_New(Py_ssize_t size)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_115">115</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from4_116">116</td><td nowrap="nowrap"> Return a new writable buffer object that maintains its own memory buffer of</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to4__top">t</a></td><td class="diff_header" id="from4_117">117-</td><td nowrap="nowrap"> *size* bytes. :exc:`ValueError` is returned if *size* is not zero or<span class="diff_sub"> positive.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to4__top">t</a></td><td class="diff_header" id="to4_413">413+</td><td nowrap="nowrap"> *size* bytes. :exc:`ValueError` is returned if *size* is not zero or</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_118">118-</td><td nowrap="nowrap"><span class="diff_sub"> Note that the memory buffer (as returned by :cfunc:`PyObject_AsWriteBuffer`) is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_414">414+</td><td nowrap="nowrap"><span class="diff_add"> positive. Note that the memory buffer (as returned by</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from4_119">119-</td><td nowrap="nowrap"><span class="diff_sub"> not specifically aligned.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_415">415+</td><td nowrap="nowrap"><span class="diff_add"> :cfunc:`PyObject_AsWriteBuffer`) is not specifically aligned.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_416">416+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_417">417+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_418">418+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *size*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to4_419">419+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/bytearray.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,90 @@ +--- r262/c-api/bytearray.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/bytearray.rst 2009-09-20 16:14:47.015125000 +0900 +@@ -11,68 +11,77 @@ + + + .. ctype:: PyByteArrayObject + + This subtype of :ctype:`PyObject` represents a Python bytearray object. + + + .. cvar:: PyTypeObject PyByteArray_Type + + This instance of :ctype:`PyTypeObject` represents the Python bytearray type; + it is the same object as ``bytearray`` in the Python layer. + ++Type check macros ++^^^^^^^^^^^^^^^^^ + + .. cfunction:: int PyByteArray_Check(PyObject *o) + + Return true if the object *o* is a bytearray object or an instance of a + subtype of the bytearray type. + + + .. cfunction:: int PyByteArray_CheckExact(PyObject *o) + + Return true if the object *o* is a bytearray object, but not an instance of a + subtype of the bytearray type. + + ++Direct API functions ++^^^^^^^^^^^^^^^^^^^^ ++ + .. cfunction:: PyObject* PyByteArray_FromObject(PyObject *o) + + Return a new bytearray object from any object, *o*, that implements the + buffer protocol. + + .. XXX expand about the buffer protocol, at least somewhere + + + .. cfunction:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len) + + Create a new bytearray object from *string* and its length, *len*. On + failure, *NULL* is returned. + + +-.. cfunction:: Py_ssize_t PyByteArray_Size(PyObject *bytearray) ++.. cfunction:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b) + +- Return the size of *bytearray* after checking for a *NULL* pointer. ++ Concat bytearrays *a* and *b* and return a new bytearray with the result. + + +-.. cfunction:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray) ++.. cfunction:: Py_ssize_t PyByteArray_Size(PyObject *bytearray) + +- Macro version of :cfunc:`PyByteArray_Size` that doesn't do pointer checking. ++ Return the size of *bytearray* after checking for a *NULL* pointer. + + + .. cfunction:: char* PyByteArray_AsString(PyObject *bytearray) + + Return the contents of *bytearray* as a char array after checking for a + *NULL* pointer. + + +-.. cfunction:: char* PyByteArray_AS_STRING(PyObject *bytearray) ++.. cfunction:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len) + +- Macro version of :cfunc:`PyByteArray_AsString` that doesn't check pointers. ++ Resize the internal buffer of *bytearray* to *len*. + ++Macros ++^^^^^^ + +-.. cfunction:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b) ++These macros trade safety for speed and they don't check pointers. + +- Concat bytearrays *a* and *b* and return a new bytearray with the result. ++.. cfunction:: char* PyByteArray_AS_STRING(PyObject *bytearray) + ++ Macro version of :cfunc:`PyByteArray_AsString`. + +-.. cfunction:: PyObject* PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len) + +- Resize the internal buffer of *bytearray* to *len*. ++.. cfunction:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray) ++ ++ Macro version of :cfunc:`PyByteArray_Size`. ======================================= --- /dev/null +++ /c-api/diff/bytearray.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,83 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to5__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/bytearray.rst => r266/c-api/bytearray.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to5__0"></td><td class="diff_header" id="from5_15">15</td><td nowrap="nowrap"> This subtype of :ctype:`PyObject` represents a Python bytearray object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_16">16</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_17">17</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_18">18</td><td nowrap="nowrap">.. cvar:: PyTypeObject PyByteArray_Type</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_19">19</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_20">20</td><td nowrap="nowrap"> This instance of :ctype:`PyTypeObject` represents the Python bytearray type;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_21">21</td><td nowrap="nowrap"> it is the same object as ``bytearray`` in the Python layer.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_22">22</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to5__1">n</a></td><td class="diff_header" id="to5_23">23+</td><td nowrap="nowrap"><span class="diff_add">Type check macros</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_24">24+</td><td nowrap="nowrap"><span class="diff_add">^^^^^^^^^^^^^^^^^</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from5_23">23</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_24">24</td><td nowrap="nowrap">.. cfunction:: int PyByteArray_Check(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_25">25</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_26">26</td><td nowrap="nowrap"> Return true if the object *o* is a bytearray object or an instance of a</td></tr> <tr><td class="diff_next" id="difflib_chg_to5__1"></td><td class="diff_header" id="from5_27">27</td><td nowrap="nowrap"> subtype of the bytearray type.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_28">28</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_29">29</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_30">30</td><td nowrap="nowrap">.. cfunction:: int PyByteArray_CheckExact(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_31">31</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_32">32</td><td nowrap="nowrap"> Return true if the object *o* is a bytearray object, but not an instance of a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_33">33</td><td nowrap="nowrap"> subtype of the bytearray type.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_34">34</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to5__2">n</a></td><td class="diff_header" id="to5_37">37+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_38">38+</td><td nowrap="nowrap"><span class="diff_add">Direct API functions</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_39">39+</td><td nowrap="nowrap"><span class="diff_add">^^^^^^^^^^^^^^^^^^^^</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from5_35">35</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_36">36</td><td nowrap="nowrap">.. cfunction:: PyObject* PyByteArray_FromObject(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_37">37</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_38">38</td><td nowrap="nowrap"> Return a new bytearray object from any object, *o*, that implements the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_39">39</td><td nowrap="nowrap"> buffer protocol.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_40">40</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_41">41</td><td nowrap="nowrap"> .. XXX expand about the buffer protocol, at least somewhere</td></tr> <tr><td class="diff_next" id="difflib_chg_to5__2"></td><td class="diff_header" id="from5_42">42</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_43">43</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_44">44</td><td nowrap="nowrap">.. cfunction:: PyObject* PyByteArray_FromStringAndSize(const char *string, Py_ssize_t len)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_45">45</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_46">46</td><td nowrap="nowrap"> Create a new bytearray object from *string* and its length, *len*. On</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_47">47</td><td nowrap="nowrap"> failure, *NULL* is returned.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_48">48</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_49">49</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next" id="difflib_chg_to5__3"><a href="#difflib_chg_to5__3">n</a></td><td class="diff_header" id="to5_55">55+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_56">56+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_57">57+</td><td nowrap="nowrap"><span class="diff_add"> Concat bytearrays *a* and *b* and return a new bytearray with the result.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_58">58+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_59">59+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from5_50">50</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PyByteArray_Size(PyObject *bytearray)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_51">51</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_52">52</td><td nowrap="nowrap"> Return the size of *bytearray* after checking for a *NULL* pointer.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to5__4">n</a></td><td class="diff_header" id="from5_53">53-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from5_54">54-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from5_55">55-</td><td nowrap="nowrap"><span class="diff_sub">.. cfunction:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from5_56">56-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from5_57">57-</td><td nowrap="nowrap"><span class="diff_sub"> Macro version of :cfunc:`PyByteArray_Size` that doesn't do pointer checking.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to5__4"></td><td class="diff_header" id="from5_58">58</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_59">59</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_60">60</td><td nowrap="nowrap">.. cfunction:: char* PyByteArray_AsString(PyObject *bytearray)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_61">61</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_62">62</td><td nowrap="nowrap"> Return the contents of *bytearray* as a char array after checking for a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_63">63</td><td nowrap="nowrap"> *NULL* pointer.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_64">64</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_65">65</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to5__5">n</a></td><td class="diff_header" id="to5_71">71+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: int PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_72">72+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_73">73+</td><td nowrap="nowrap"><span class="diff_add"> Resize the internal buffer of *bytearray* to *len*.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to5__5"></td><td class="diff_header" id="to5_74">74+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_75">75+</td><td nowrap="nowrap"><span class="diff_add">Macros</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_76">76+</td><td nowrap="nowrap"><span class="diff_add">^^^^^^</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to5__6"></td><td class="diff_header" id="to5_77">77+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to5_78">78+</td><td nowrap="nowrap"><span class="diff_add">These macros trade safety for speed and they don't check pointers.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to5__7"></td><td class="diff_header" id="to5_79">79+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from5_66">66</td><td nowrap="nowrap">.. cfunction:: char* PyByteArray_AS_STRING(PyObject *bytearray)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_67">67</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to5__6">n</a></td><td class="diff_header" id="from5_68">68-</td><td nowrap="nowrap"> Macro version of :cfunc:`PyByteArray_AsString`<span class="diff_sub"> that doesn't check pointers</span>.</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to5__6">n</a></td><td class="diff_header" id="to5_82">82+</td><td nowrap="nowrap"> Macro version of :cfunc:`PyByteArray_AsString`.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from5_69">69</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from5_70">70</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to5__7">n</a></td><td class="diff_header" id="from5_71">71-</td><td nowrap="nowrap"><span class="diff_sub">.. cfunction:: PyObject* PyByteArray_Concat(PyObject *a, PyObject *b)</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to5__7">n</a></td><td class="diff_header" id="to5_85">85+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: Py_ssize_t PyByteArray_GET_SIZE(PyObject *bytearray)</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from5_72">72</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to5__top">t</a></td><td class="diff_header" id="from5_73">73-</td><td nowrap="nowrap"><span class="diff_sub"> Concat bytearrays *a* and *b* and return a new bytearray with the result.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to5__top">t</a></td><td class="diff_header" id="to5_87">87+</td><td nowrap="nowrap"><span class="diff_add"> Macro version of :cfunc:`PyByteArray_Size`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from5_74">74-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from5_75">75-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from5_76">76-</td><td nowrap="nowrap"><span class="diff_sub">.. cfunction:: PyObject* PyByteArray_Resize(PyObject *bytearray, Py_ssize_t len)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from5_77">77-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from5_78">78-</td><td nowrap="nowrap"><span class="diff_sub"> Resize the internal buffer of *bytearray* to *len*.</span></td></tr> + </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/datetime.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,32 @@ +--- r262/c-api/datetime.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/datetime.rst 2010-06-27 03:53:49.395786000 +0900 +@@ -1,25 +1,26 @@ + .. highlightlang:: c + + .. _datetimeobjects: + + DateTime Objects + ---------------- + + Various date and time objects are supplied by the :mod:`datetime` module. + Before using any of these functions, the header file :file:`datetime.h` must be + included in your source (note that this is not included by :file:`Python.h`), +-and the macro :cfunc:`PyDateTime_IMPORT` must be invoked. The macro puts a +-pointer to a C structure into a static variable, ``PyDateTimeAPI``, that is +-used by the following macros. ++and the macro :cmacro:`PyDateTime_IMPORT` must be invoked, usually as part of ++the module initialisation function. The macro puts a pointer to a C structure ++into a static variable, :cdata:`PyDateTimeAPI`, that is used by the following ++macros. + + Type-check macros: + + + .. cfunction:: int PyDate_Check(PyObject *ob) + + Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of + :cdata:`PyDateTime_DateType`. *ob* must not be *NULL*. + + .. versionadded:: 2.4 + + ======================================= --- /dev/null +++ /c-api/diff/datetime.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,55 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to6__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/datetime.rst => r266/c-api/datetime.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to6__0"></td><td class="diff_header" id="from6_3">3</td><td nowrap="nowrap">.. _datetimeobjects:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_4">4</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_5">5</td><td nowrap="nowrap">DateTime Objects</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_6">6</td><td nowrap="nowrap">----------------</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_7">7</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_8">8</td><td nowrap="nowrap">Various date and time objects are supplied by the :mod:`datetime` module.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_9">9</td><td nowrap="nowrap">Before using any of these functions, the header file :file:`datetime.h` must be</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_10">10</td><td nowrap="nowrap">included in your source (note that this is not included by :file:`Python.h`),</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to6__top">t</a></td><td class="diff_header" id="from6_11">11-</td><td nowrap="nowrap"><span class="diff_sub">and the macro :cfunc:`PyDateTime_IMPORT` must be invoked. The macro puts a</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to6__top">t</a></td><td class="diff_header" id="to6_11">11+</td><td nowrap="nowrap"><span class="diff_add">and the macro :cmacro:`PyDateTime_IMPORT` must be invoked, usually as part of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from6_12">12-</td><td nowrap="nowrap"><span class="diff_sub">pointer to a C structure into a static variable, ``PyDateTimeAPI``, that is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to6_12">12+</td><td nowrap="nowrap"><span class="diff_add">the module initialisation function. The macro puts a pointer to a C structure</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from6_13">13-</td><td nowrap="nowrap"><span class="diff_sub">used by the following macros.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to6_13">13+</td><td nowrap="nowrap"><span class="diff_add">into a static variable, :cdata:`PyDateTimeAPI`, that is used by the following</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to6_14">14+</td><td nowrap="nowrap"><span class="diff_add">macros.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from6_14">14</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_15">15</td><td nowrap="nowrap">Type-check macros:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_16">16</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_17">17</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_18">18</td><td nowrap="nowrap">.. cfunction:: int PyDate_Check(PyObject *ob)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_19">19</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_20">20</td><td nowrap="nowrap"> Return true if *ob* is of type :cdata:`PyDateTime_DateType` or a subtype of</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from6_21">21</td><td nowrap="nowrap"> :cdata:`PyDateTime_DateType`. *ob* must not be *NULL*.</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/dict.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,278 @@ +--- r262/c-api/dict.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/dict.rst 2009-04-29 17:00:05.894850000 +0900 +@@ -10,211 +10,224 @@ + + .. ctype:: PyDictObject + + This subtype of :ctype:`PyObject` represents a Python dictionary object. + + + .. cvar:: PyTypeObject PyDict_Type + + .. index:: + 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) + + Return true if *p* is a dict object or an instance of a subtype of the dict + type. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + + .. 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 + + + .. cfunction:: PyObject* PyDict_New() + + Return a new empty dictionary, or *NULL* on failure. + + + .. 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 + + + .. cfunction:: void PyDict_Clear(PyObject *p) + + Empty an existing dictionary of all key-value pairs. + + + .. 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 + + + .. cfunction:: PyObject* PyDict_Copy(PyObject *p) + + Return a new dictionary that contains the same key-value pairs as *p*. + + .. versionadded:: 1.6 + + + .. 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) + + Remove the entry in dictionary *p* which has a key specified by the string + *key*. Return ``0`` on success or ``-1`` on failure. + + + .. 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) + + This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a + :ctype:`char\*`, rather than a :ctype:`PyObject\*`. + + + .. 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:: + + PyObject *key, *value; + Py_ssize_t pos = 0; + + while (PyDict_Next(self->dict, &pos, &key, &value)) { + /* do something interesting with the values... */ + ... + } + +- 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; + + while (PyDict_Next(self->dict, &pos, &key, &value)) { + int i = PyInt_AS_LONG(value) + 1; + PyObject *o = PyInt_FromLong(i); + if (o == NULL) + return -1; + if (PyDict_SetItem(self->dict, key, o) < 0) { + Py_DECREF(o); + return -1; + } + 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 + + + .. cfunction:: int PyDict_Update(PyObject *a, PyObject *b) + + This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in + Python. Return ``0`` on success or ``-1`` if an exception was raised. + + .. versionadded:: 2.2 + + + .. 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: + if override or key not in a: + a[key] = value + + .. versionadded:: 2.2 ======================================= --- /dev/null +++ /c-api/diff/dict.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,163 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to7__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/dict.rst => r266/c-api/dict.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to7__0"></td><td class="diff_header" id="from7_14">14</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_15">15</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_16">16</td><td nowrap="nowrap">.. cvar:: PyTypeObject PyDict_Type</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_17">17</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_18">18</td><td nowrap="nowrap"> .. index::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_19">19</td><td nowrap="nowrap"> single: DictType (in module types)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_20">20</td><td nowrap="nowrap"> single: DictionaryType (in module types)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_21">21</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__1">n</a></td><td class="diff_header" id="from7_22">22-</td><td nowrap="nowrap"> This instance of :ctype:`PyTypeObject` represents the Python dictionary<span class="diff_sub"> type.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__1">n</a></td><td class="diff_header" id="to7_22">22+</td><td nowrap="nowrap"> This instance of :ctype:`PyTypeObject` represents the Python dictionary</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_23">23-</td><td nowrap="nowrap"> This is exposed to Python programs as ``dict`` and<span class="diff_sub"> ``types.DictType``.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_23">23+</td><td nowrap="nowrap"> <span class="diff_add"> type.</span> This is exposed to Python programs as ``dict`` and</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_24">24+</td><td nowrap="nowrap"><span class="diff_add"> ``types.DictType``.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_24">24</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_25">25</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_26">26</td><td nowrap="nowrap">.. cfunction:: int PyDict_Check(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_27">27</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_28">28</td><td nowrap="nowrap"> Return true if *p* is a dict object or an instance of a subtype of the dict</td></tr> <tr><td class="diff_next" id="difflib_chg_to7__1"></td><td class="diff_header" id="from7_29">29</td><td nowrap="nowrap"> type.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_30">30</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_31">31</td><td nowrap="nowrap"> .. versionchanged:: 2.2</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_32">32</td><td nowrap="nowrap"> Allowed subtypes to be accepted.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_33">33</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_34">34</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_35">35</td><td nowrap="nowrap">.. cfunction:: int PyDict_CheckExact(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_36">36</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__2">n</a></td><td class="diff_header" id="from7_37">37-</td><td nowrap="nowrap"> Return true if *p* is a dict object, but not an instance of a subtype of<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__2">n</a></td><td class="diff_header" id="to7_38">38+</td><td nowrap="nowrap"> Return true if *p* is a dict object, but not an instance of a subtype of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_38">38-</td><td nowrap="nowrap"> dict type.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_39">39+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> dict type.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_39">39</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_40">40</td><td nowrap="nowrap"> .. versionadded:: 2.4</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_41">41</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to7__2"></td><td class="diff_header" id="from7_42">42</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_43">43</td><td nowrap="nowrap">.. cfunction:: PyObject* PyDict_New()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_44">44</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_45">45</td><td nowrap="nowrap"> Return a new empty dictionary, or *NULL* on failure.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_46">46</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_47">47</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_48">48</td><td nowrap="nowrap">.. cfunction:: PyObject* PyDictProxy_New(PyObject *dict)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_49">49</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__3">n</a></td><td class="diff_header" id="from7_50">50-</td><td nowrap="nowrap"> Return a proxy object for a mapping which enforces read-only behavior.<span class="diff_sub"> This is</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__3">n</a></td><td class="diff_header" id="to7_51">51+</td><td nowrap="nowrap"> Return a proxy object for a mapping which enforces read-only behavior.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_51">51-</td><td nowrap="nowrap"> normally used to create a proxy to prevent modification of the<span class="diff_sub"> dictionary for</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_52">52+</td><td nowrap="nowrap"> <span class="diff_add"> This is</span> normally used to create a proxy to prevent modification of the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_52">52-</td><td nowrap="nowrap"> non-dynamic class types.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_53">53+</td><td nowrap="nowrap"> <span class="diff_add"> dictionary for</span> non-dynamic class types.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_53">53</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_54">54</td><td nowrap="nowrap"> .. versionadded:: 2.2</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_55">55</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to7__3"></td><td class="diff_header" id="from7_56">56</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_57">57</td><td nowrap="nowrap">.. cfunction:: void PyDict_Clear(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_58">58</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_59">59</td><td nowrap="nowrap"> Empty an existing dictionary of all key-value pairs.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_60">60</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_61">61</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_62">62</td><td nowrap="nowrap">.. cfunction:: int PyDict_Contains(PyObject *p, PyObject *key)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_63">63</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__4">n</a></td><td class="diff_header" id="from7_64">64-</td><td nowrap="nowrap"> Determine if dictionary *p* contains *key*. If an item in *p* is matches<span class="diff_sub"> *key*,</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__4">n</a></td><td class="diff_header" id="to7_65">65+</td><td nowrap="nowrap"> Determine if dictionary *p* contains *key*. If an item in *p* is matches</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_65">65-</td><td nowrap="nowrap"> return ``1``, otherwise return ``0``. On error, return ``-1``.<span class="diff_sub"> This is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_66">66+</td><td nowrap="nowrap"> <span class="diff_add"> *key*,</span> return ``1``, otherwise return ``0``. On error, return ``-1``.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_66">66-</td><td nowrap="nowrap"> equivalent to the Python expression ``key in p``.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_67">67+</td><td nowrap="nowrap"> <span class="diff_add"> This is</span> equivalent to the Python expression ``key in p``.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_67">67</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_68">68</td><td nowrap="nowrap"> .. versionadded:: 2.4</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_69">69</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_70">70</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_71">71</td><td nowrap="nowrap">.. cfunction:: PyObject* PyDict_Copy(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_72">72</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to7__4"></td><td class="diff_header" id="from7_73">73</td><td nowrap="nowrap"> Return a new dictionary that contains the same key-value pairs as *p*.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_74">74</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_75">75</td><td nowrap="nowrap"> .. versionadded:: 1.6</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_76">76</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_77">77</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_78">78</td><td nowrap="nowrap">.. cfunction:: int PyDict_SetItem(PyObject *p, PyObject *key, PyObject *val)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_79">79</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_80">80</td><td nowrap="nowrap"> Insert *value* into the dictionary *p* with a key of *key*. *key* must be</td></tr><tr><td class="diff_next" id="difflib_chg_to7__5"><a href="#difflib_chg_to7__5">n</a></td><td class="diff_header" id="from7_81">81-</td><td nowrap="nowrap"> :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return<span class="diff_sub"> ``0``</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to7__5"><a href="#difflib_chg_to7__5">n</a></td><td class="diff_header" id="to7_82">82+</td><td nowrap="nowrap"> :term:`hashable`; if it isn't, :exc:`TypeError` will be raised. Return</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_82">82-</td><td nowrap="nowrap"> on success or ``-1`` on failure.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_83">83+</td><td nowrap="nowrap"> <span class="diff_add"> ``0``</span> on success or ``-1`` on failure.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_83">83</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_84">84</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_85">85</td><td nowrap="nowrap">.. cfunction:: int PyDict_SetItemString(PyObject *p, const char *key, PyObject *val)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_86">86</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_87">87</td><td nowrap="nowrap"> .. index:: single: PyString_FromString()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_88">88</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next" id="difflib_chg_to7__6"><a href="#difflib_chg_to7__6">n</a></td><td class="diff_header" id="from7_89">89-</td><td nowrap="nowrap"> Insert *value* into the dictionary *p* using *key* as a key. *key* should<span class="diff_sub"> be a</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to7__6"><a href="#difflib_chg_to7__6">n</a></td><td class="diff_header" id="to7_90">90+</td><td nowrap="nowrap"> Insert *value* into the dictionary *p* using *key* as a key. *key* should</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_90">90-</td><td nowrap="nowrap"><span class="diff_sub"> :ctype:`char\*`. The key object is created using ``PyString_FromString(key)``.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_91">91+</td><td nowrap="nowrap"><span class="diff_add"> be a :ctype:`char\*`. The key object is created using</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_91">91-</td><td nowrap="nowrap"><span class="diff_sub"> Return ``0`` on success or ``-1`` on failure.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_92">92+</td><td nowrap="nowrap"><span class="diff_add"> ``PyString_FromString(key)``. Return ``0`` on success or ``-1`` on</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_93">93+</td><td nowrap="nowrap"><span class="diff_add"> failure.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_92">92</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_93">93</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_94">94</td><td nowrap="nowrap">.. cfunction:: int PyDict_DelItem(PyObject *p, PyObject *key)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_95">95</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__7">n</a></td><td class="diff_header" id="from7_96">96-</td><td nowrap="nowrap"> Remove the entry in dictionary *p* with key *key*. *key* must be hashable;<span class="diff_sub"> if it</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__7">n</a></td><td class="diff_header" id="to7_98">98+</td><td nowrap="nowrap"> Remove the entry in dictionary *p* with key *key*. *key* must be hashable;</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_97">97-</td><td nowrap="nowrap"> isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``<span class="diff_sub"> on</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_99">99+</td><td nowrap="nowrap"> <span class="diff_add"> if it</span> isn't, :exc:`TypeError` is raised. Return ``0`` on success or ``-1``</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_98">98-</td><td nowrap="nowrap"> failure.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_100">100+</td><td nowrap="nowrap"> <span class="diff_add"> on</span> failure.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_99">99</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_100">100</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to7__7"></td><td class="diff_header" id="from7_101">101</td><td nowrap="nowrap">.. cfunction:: int PyDict_DelItemString(PyObject *p, char *key)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_102">102</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_103">103</td><td nowrap="nowrap"> Remove the entry in dictionary *p* which has a key specified by the string</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_104">104</td><td nowrap="nowrap"> *key*. Return ``0`` on success or ``-1`` on failure.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_105">105</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_106">106</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_107">107</td><td nowrap="nowrap">.. cfunction:: PyObject* PyDict_GetItem(PyObject *p, PyObject *key)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_108">108</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__8">n</a></td><td class="diff_header" id="from7_109">109-</td><td nowrap="nowrap"> Return the object from dictionary *p* which has a key *key*. Return *NULL*<span class="diff_sub"> if</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__8">n</a></td><td class="diff_header" id="to7_111">111+</td><td nowrap="nowrap"> Return the object from dictionary *p* which has a key *key*. Return *NULL*</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_110">110-</td><td nowrap="nowrap"> the key *key* is not present, but *without* setting an exception.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_112">112+</td><td nowrap="nowrap"> <span class="diff_add"> if</span> the key *key* is not present, but *without* setting an exception.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_111">111</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_112">112</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to7__8"></td><td class="diff_header" id="from7_113">113</td><td nowrap="nowrap">.. cfunction:: PyObject* PyDict_GetItemString(PyObject *p, const char *key)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_114">114</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_115">115</td><td nowrap="nowrap"> This is the same as :cfunc:`PyDict_GetItem`, but *key* is specified as a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_116">116</td><td nowrap="nowrap"> :ctype:`char\*`, rather than a :ctype:`PyObject\*`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_117">117</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_118">118</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to7__9"></td><td class="diff_header" id="from7_119">119</td><td nowrap="nowrap">.. cfunction:: PyObject* PyDict_Items(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_120">120</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__9">n</a></td><td class="diff_header" id="from7_121">121-</td><td nowrap="nowrap"> Return a :ctype:`PyListObject` containing all the items from the<span class="diff_sub"> dictionary, as</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__9">n</a></td><td class="diff_header" id="to7_123">123+</td><td nowrap="nowrap"> Return a :ctype:`PyListObject` containing all the items from the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_122">122-</td><td nowrap="nowrap"><span class="diff_sub"> in the dictionary method :meth:`dict.items`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_124">124+</td><td nowrap="nowrap"><span class="diff_add"> dictionary, as in the dictionary method :meth:`dict.items`.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_123">123</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_124">124</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to7__10"></td><td class="diff_header" id="from7_125">125</td><td nowrap="nowrap">.. cfunction:: PyObject* PyDict_Keys(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_126">126</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__10">n</a></td><td class="diff_header" id="from7_127">127-</td><td nowrap="nowrap"> Return a :ctype:`PyListObject` containing all the keys from the dictionary,<span class="diff_sub"> as</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__10">n</a></td><td class="diff_header" id="to7_129">129+</td><td nowrap="nowrap"> Return a :ctype:`PyListObject` containing all the keys from the dictionary,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_128">128-</td><td nowrap="nowrap"> in the dictionary method :meth:`dict.keys`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_130">130+</td><td nowrap="nowrap"> <span class="diff_add"> as</span> in the dictionary method :meth:`dict.keys`.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_129">129</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_130">130</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_131">131</td><td nowrap="nowrap">.. cfunction:: PyObject* PyDict_Values(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_132">132</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next" id="difflib_chg_to7__11"><a href="#difflib_chg_to7__11">n</a></td><td class="diff_header" id="from7_133">133-</td><td nowrap="nowrap"> Return a :ctype:`PyListObject` containing all the values from the<span class="diff_sub"> dictionary</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to7__11"><a href="#difflib_chg_to7__11">n</a></td><td class="diff_header" id="to7_135">135+</td><td nowrap="nowrap"> Return a :ctype:`PyListObject` containing all the values from the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_134">134-</td><td nowrap="nowrap"><span class="diff_sub"> *p*, as in the dictionary method :meth:`dict.values`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_136">136+</td><td nowrap="nowrap"><span class="diff_add"> dictionary *p*, as in the dictionary method :meth:`dict.values`.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_135">135</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_136">136</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_137">137</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PyDict_Size(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_138">138</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_139">139</td><td nowrap="nowrap"> .. index:: builtin: len</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_140">140</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__12">n</a></td><td class="diff_header" id="from7_141">141-</td><td nowrap="nowrap"> Return the number of items in the dictionary. This is equivalent to<span class="diff_sub"> ``len(p)``</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__12">n</a></td><td class="diff_header" id="to7_143">143+</td><td nowrap="nowrap"> Return the number of items in the dictionary. This is equivalent to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_142">142-</td><td nowrap="nowrap"> on a dictionary.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_144">144+</td><td nowrap="nowrap"> <span class="diff_add"> ``len(p)``</span> on a dictionary.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to7__12"></td><td class="diff_header" id="to7_145">145+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_146">146+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_147">147+</td><td nowrap="nowrap"><span class="diff_add"> This function returned an :ctype:`int` type. This might require changes</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_148">148+</td><td nowrap="nowrap"><span class="diff_add"> in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_143">143</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_144">144</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_145">145</td><td nowrap="nowrap">.. cfunction:: int PyDict_Next(PyObject *p, Py_ssize_t *ppos, PyObject **pkey, PyObject **pvalue)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_146">146</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__13">n</a></td><td class="diff_header" id="from7_147">147-</td><td nowrap="nowrap"> Iterate over all key-value pairs in the dictionary *p*. The<span class="diff_sub"> :ctype:`int`</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__13">n</a></td><td class="diff_header" id="to7_153">153+</td><td nowrap="nowrap"> Iterate over all key-value pairs in the dictionary *p*. The</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_148">148-</td><td nowrap="nowrap"><span class="diff_sub"> referred to by *ppos* must be initialized to ``0`` prior to the first call to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_154">154+</td><td nowrap="nowrap"><span class="diff_add"> :ctype:`Py_ssize_t` referred to by *ppos* must be initialized to ``0``</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_149">149-</td><td nowrap="nowrap"><span class="diff_sub"> this function to start the iteration; the function returns true for each pair in</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_155">155+</td><td nowrap="nowrap"><span class="diff_add"> prior to the first call to this function to start the iteration; the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_150">150-</td><td nowrap="nowrap"><span class="diff_sub"> the dictionary, and false once all pairs have been reported. The parameters</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_156">156+</td><td nowrap="nowrap"><span class="diff_add"> function returns true for each pair in the dictionary, and false once all</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_151">151-</td><td nowrap="nowrap"><span class="diff_sub"> *pkey* and *pvalue* should either point to :ctype:`PyObject\*` variables that</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_157">157+</td><td nowrap="nowrap"><span class="diff_add"> pairs have been reported. The parameters *pkey* and *pvalue* should either</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_152">152-</td><td nowrap="nowrap"><span class="diff_sub"> will be filled in with each key and value, respectively, or may be *NULL*. Any</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_158">158+</td><td nowrap="nowrap"><span class="diff_add"> point to :ctype:`PyObject\*` variables that will be filled in with each key</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_153">153-</td><td nowrap="nowrap"><span class="diff_sub"> references returned through them are borrowed. *ppos* should not be altered</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_159">159+</td><td nowrap="nowrap"><span class="diff_add"> and value, respectively, or may be *NULL*. Any references returned through</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_160">160+</td><td nowrap="nowrap"><span class="diff_add"> them are borrowed. *ppos* should not be altered during iteration. Its</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_154">154-</td><td nowrap="nowrap"> <span class="diff_sub"> during iteration. Its</span> value represents offsets within the internal dictionary</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_161">161+</td><td nowrap="nowrap"> value represents offsets within the internal dictionary<span class="diff_add"> structure, and</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_155">155-</td><td nowrap="nowrap"> structure<span class="diff_sub">, and since the structure</span> is sparse, the offsets are not consecutive.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_162">162+</td><td nowrap="nowrap"> <span class="diff_add"> since the</span> structure is sparse, the offsets are not consecutive.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_156">156</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_157">157</td><td nowrap="nowrap"> For example::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_158">158</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to7__13"></td><td class="diff_header" id="from7_159">159</td><td nowrap="nowrap"> PyObject *key, *value;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_160">160</td><td nowrap="nowrap"> Py_ssize_t pos = 0;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_161">161</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_162">162</td><td nowrap="nowrap"> while (PyDict_Next(self->dict, &pos, &key, &value)) {</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_163">163</td><td nowrap="nowrap"> /* do something interesting with the values... */</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_164">164</td><td nowrap="nowrap"> ...</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_165">165</td><td nowrap="nowrap"> }</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_166">166</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__14">n</a></td><td class="diff_header" id="from7_167">167-</td><td nowrap="nowrap"> The dictionary *p* should not be mutated during iteration. It is safe<span class="diff_sub"> (since</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__14">n</a></td><td class="diff_header" id="to7_174">174+</td><td nowrap="nowrap"> The dictionary *p* should not be mutated during iteration. It is safe</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_168">168-</td><td nowrap="nowrap"> Python 2.1) to modify the values of the keys as you iterate over the<span class="diff_sub"> dictionary,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_175">175+</td><td nowrap="nowrap"> <span class="diff_add"> (since</span> Python 2.1) to modify the values of the keys as you iterate over the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_169">169-</td><td nowrap="nowrap"> but only so long as the set of keys does not change. For<span class="diff_sub"> example::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_176">176+</td><td nowrap="nowrap"> <span class="diff_add"> dictionary,</span> but only so long as the set of keys does not change. For</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_177">177+</td><td nowrap="nowrap"><span class="diff_add"> example::</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_170">170</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_171">171</td><td nowrap="nowrap"> PyObject *key, *value;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_172">172</td><td nowrap="nowrap"> Py_ssize_t pos = 0;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_173">173</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_174">174</td><td nowrap="nowrap"> while (PyDict_Next(self->dict, &pos, &key, &value)) {</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_175">175</td><td nowrap="nowrap"> int i = PyInt_AS_LONG(value) + 1;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_176">176</td><td nowrap="nowrap"> PyObject *o = PyInt_FromLong(i);</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_177">177</td><td nowrap="nowrap"> if (o == NULL)</td></tr> <tr><td class="diff_next" id="difflib_chg_to7__14"></td><td class="diff_header" id="from7_178">178</td><td nowrap="nowrap"> return -1;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_179">179</td><td nowrap="nowrap"> if (PyDict_SetItem(self->dict, key, o) < 0) {</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_180">180</td><td nowrap="nowrap"> Py_DECREF(o);</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_181">181</td><td nowrap="nowrap"> return -1;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_182">182</td><td nowrap="nowrap"> }</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_183">183</td><td nowrap="nowrap"> Py_DECREF(o);</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_184">184</td><td nowrap="nowrap"> }</td></tr> <tr><td class="diff_next" id="difflib_chg_to7__15"></td><td class="diff_header" id="from7_185">185</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__15">n</a></td><td class="diff_header" id="to7_194">194+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_195">195+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int *` type for *ppos*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_196">196+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_197">197+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_186">186</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_187">187</td><td nowrap="nowrap">.. cfunction:: int PyDict_Merge(PyObject *a, PyObject *b, int override)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_188">188</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__16">n</a></td><td class="diff_header" id="from7_189">189-</td><td nowrap="nowrap"> Iterate over mapping object *b* adding key-value pairs to dictionary *a*.<span class="diff_sub"> *b*</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__16">n</a></td><td class="diff_header" id="to7_201">201+</td><td nowrap="nowrap"> Iterate over mapping object *b* adding key-value pairs to dictionary *a*.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_190">190-</td><td nowrap="nowrap"> may be a dictionary, or any object supporting :func:`PyMapping_Keys`<span class="diff_sub"> and</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_202">202+</td><td nowrap="nowrap"> <span class="diff_add"> *b*</span> may be a dictionary, or any object supporting :func:`PyMapping_Keys`</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_191">191-</td><td nowrap="nowrap"> :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*<span class="diff_sub"> will be</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_203">203+</td><td nowrap="nowrap"> <span class="diff_add"> and</span> :func:`PyObject_GetItem`. If *override* is true, existing pairs in *a*</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_192">192-</td><td nowrap="nowrap"> replaced if a matching key is found in *b*, otherwise pairs will<span class="diff_sub"> only be added</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_204">204+</td><td nowrap="nowrap"> <span class="diff_add"> will be</span> replaced if a matching key is found in *b*, otherwise pairs will</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_193">193-</td><td nowrap="nowrap"> if there is not a matching key in *a*. Return ``0`` on<span class="diff_sub"> success or ``-1`` if an</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_205">205+</td><td nowrap="nowrap"> <span class="diff_add"> only be added</span> if there is not a matching key in *a*. Return ``0`` on</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_194">194-</td><td nowrap="nowrap"><span class="diff_sub"> exception was raised.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_206">206+</td><td nowrap="nowrap"><span class="diff_add"> success or ``-1`` if an exception was raised.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_195">195</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_196">196</td><td nowrap="nowrap"> .. versionadded:: 2.2</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_197">197</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_198">198</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_199">199</td><td nowrap="nowrap">.. cfunction:: int PyDict_Update(PyObject *a, PyObject *b)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_200">200</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to7__16"></td><td class="diff_header" id="from7_201">201</td><td nowrap="nowrap"> This is the same as ``PyDict_Merge(a, b, 1)`` in C, or ``a.update(b)`` in</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_202">202</td><td nowrap="nowrap"> Python. Return ``0`` on success or ``-1`` if an exception was raised.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_203">203</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_204">204</td><td nowrap="nowrap"> .. versionadded:: 2.2</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_205">205</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_206">206</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_207">207</td><td nowrap="nowrap">.. cfunction:: int PyDict_MergeFromSeq2(PyObject *a, PyObject *seq2, int override)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_208">208</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to7__top">t</a></td><td class="diff_header" id="from7_209">209-</td><td nowrap="nowrap"> Update or merge into dictionary *a*, from the key-value pairs in *seq2*.<span class="diff_sub"> *seq2*</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to7__top">t</a></td><td class="diff_header" id="to7_221">221+</td><td nowrap="nowrap"> Update or merge into dictionary *a*, from the key-value pairs in *seq2*.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_210">210-</td><td nowrap="nowrap"> must be an iterable object producing iterable objects of length 2,<span class="diff_sub"> viewed as</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_222">222+</td><td nowrap="nowrap"> <span class="diff_add"> *seq2*</span> must be an iterable object producing iterable objects of length 2,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_211">211-</td><td nowrap="nowrap"> key-value pairs. In case of duplicate keys, the last wins if<span class="diff_sub"> *override* is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_223">223+</td><td nowrap="nowrap"> <span class="diff_add"> viewed as</span> key-value pairs. In case of duplicate keys, the last wins if</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_212">212-</td><td nowrap="nowrap"> true, else the first wins. Return ``0`` on success or ``-1``<span class="diff_sub"> if an exception was</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_224">224+</td><td nowrap="nowrap"> <span class="diff_add"> *override* is</span> true, else the first wins. Return ``0`` on success or ``-1``</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from7_213">213-</td><td nowrap="nowrap"> raised. Equivalent Python (except for the return<span class="diff_sub"> value)::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_225">225+</td><td nowrap="nowrap"> <span class="diff_add"> if an exception was</span> raised. Equivalent Python (except for the return</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to7_226">226+</td><td nowrap="nowrap"><span class="diff_add"> value)::</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from7_214">214</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_215">215</td><td nowrap="nowrap"> def PyDict_MergeFromSeq2(a, seq2, override):</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_216">216</td><td nowrap="nowrap"> for key, value in seq2:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_217">217</td><td nowrap="nowrap"> if override or key not in a:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_218">218</td><td nowrap="nowrap"> a[key] = value</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_219">219</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from7_220">220</td><td nowrap="nowrap"> .. versionadded:: 2.2</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/exceptions.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,89 @@ +--- r262/c-api/exceptions.rst 2009-02-23 19:41:11.107573000 +0900 ++++ r266/c-api/exceptions.rst 2010-03-22 04:29:04.684594000 +0900 +@@ -282,27 +282,28 @@ + + + .. cfunction:: PyObject* PyErr_SetExcFromWindowsErrWithFilename(PyObject *type, int ierr, char *filename) + + Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional + parameter specifying the exception type to be raised. Availability: Windows. + + .. versionadded:: 2.3 + + + .. cfunction:: void PyErr_BadInternalCall() + +- This is a shorthand for ``PyErr_SetString(PyExc_TypeError, message)``, where +- *message* indicates that an internal operation (e.g. a Python/C API function) +- was invoked with an illegal argument. It is mostly for internal use. ++ This is a shorthand for ``PyErr_SetString(PyExc_SystemError, message)``, ++ where *message* indicates that an internal operation (e.g. a Python/C API ++ function) was invoked with an illegal argument. It is mostly for internal ++ use. + + + .. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel) + + Issue a warning message. The *category* argument is a warning category (see + below) or *NULL*; the *message* argument is a message string. *stacklevel* is a + positive number giving a number of stack frames; the warning will be issued from + the currently executing line of code in that stack frame. A *stacklevel* of 1 + is the function calling :cfunc:`PyErr_WarnEx`, 2 is the function above that, + and so forth. + + This function normally prints a warning message to *sys.stderr*; however, it is +@@ -419,24 +420,54 @@ + .. cfunction:: void PyErr_WriteUnraisable(PyObject *obj) + + This utility function prints a warning message to ``sys.stderr`` when an + exception has been set but it is impossible for the interpreter to actually + raise the exception. It is used, for example, when an exception occurs in an + :meth:`__del__` method. + + The function is called with a single argument *obj* that identifies the context + in which the unraisable exception occurred. The repr of *obj* will be printed in + the warning message. + + ++Recursion Control ++================= ++ ++These two functions provide a way to perform safe recursive calls at the C ++level, both in the core and in extension modules. They are needed if the ++recursive code does not necessarily invoke Python code (which tracks its ++recursion depth automatically). ++ ++.. cfunction:: int Py_EnterRecursiveCall(char *where) ++ ++ Marks a point where a recursive C-level call is about to be performed. ++ ++ If :const:`USE_STACKCHECK` is defined, this function checks if the the OS ++ stack overflowed using :cfunc:`PyOS_CheckStack`. In this is the case, it ++ sets a :exc:`MemoryError` and returns a nonzero value. ++ ++ The function then checks if the recursion limit is reached. If this is the ++ case, a :exc:`RuntimeError` is set and a nonzero value is returned. ++ Otherwise, zero is returned. ++ ++ *where* should be a string such as ``" in instance check"`` to be ++ concatenated to the :exc:`RuntimeError` message caused by the recursion depth ++ limit. ++ ++.. cfunction:: void Py_LeaveRecursiveCall() ++ ++ Ends a :cfunc:`Py_EnterRecursiveCall`. Must be called once for each ++ *successful* invocation of :cfunc:`Py_EnterRecursiveCall`. ++ ++ + .. _standardexceptions: + + Standard Exceptions + =================== + + All standard Python exceptions are available as global variables whose names are + ``PyExc_`` followed by the Python exception name. These have the type + :ctype:`PyObject\*`; they are all class objects. For completeness, here are all + the variables: + + +------------------------------------+----------------------------+----------+ + | C Name | Python Name | Notes | ======================================= --- /dev/null +++ /c-api/diff/exceptions.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,87 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to8__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/exceptions.rst => r266/c-api/exceptions.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to8__0"></td><td class="diff_header" id="from8_286">286</td><td nowrap="nowrap"> Similar to :cfunc:`PyErr_SetFromWindowsErrWithFilename`, with an additional</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_287">287</td><td nowrap="nowrap"> parameter specifying the exception type to be raised. Availability: Windows.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_288">288</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_289">289</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_290">290</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_291">291</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_292">292</td><td nowrap="nowrap">.. cfunction:: void PyErr_BadInternalCall()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_293">293</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to8__1">n</a></td><td class="diff_header" id="from8_294">294-</td><td nowrap="nowrap"> This is a shorthand for ``PyErr_SetString(PyExc_<span class="diff_chg">T</span>y<span class="diff_chg">p</span>eError, message)``,<span class="diff_sub"> where</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to8__1">n</a></td><td class="diff_header" id="to8_294">294+</td><td nowrap="nowrap"> This is a shorthand for ``PyErr_SetString(PyExc_<span class="diff_chg">S</span>y<span class="diff_chg">st</span>e<span class="diff_add">m</span>Error, message)``,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from8_295">295-</td><td nowrap="nowrap"> *message* indicates that an internal operation (e.g. a Python/C API<span class="diff_sub"> function)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_295">295+</td><td nowrap="nowrap"> <span class="diff_add"> where</span> *message* indicates that an internal operation (e.g. a Python/C API</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from8_296">296-</td><td nowrap="nowrap"> was invoked with an illegal argument. It is mostly for internal<span class="diff_sub"> use.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_296">296+</td><td nowrap="nowrap"> <span class="diff_add"> function)</span> was invoked with an illegal argument. It is mostly for internal</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_297">297+</td><td nowrap="nowrap"><span class="diff_add"> use.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from8_297">297</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_298">298</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_299">299</td><td nowrap="nowrap">.. cfunction:: int PyErr_WarnEx(PyObject *category, char *message, int stacklevel)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_300">300</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_301">301</td><td nowrap="nowrap"> Issue a warning message. The *category* argument is a warning category (see</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_302">302</td><td nowrap="nowrap"> below) or *NULL*; the *message* argument is a message string. *stacklevel* is a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_303">303</td><td nowrap="nowrap"> positive number giving a number of stack frames; the warning will be issued from</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_304">304</td><td nowrap="nowrap"> the currently executing line of code in that stack frame. A *stacklevel* of 1</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to8__1"></td><td class="diff_header" id="from8_421">421</td><td nowrap="nowrap"> This utility function prints a warning message to ``sys.stderr`` when an</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_422">422</td><td nowrap="nowrap"> exception has been set but it is impossible for the interpreter to actually</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_423">423</td><td nowrap="nowrap"> raise the exception. It is used, for example, when an exception occurs in an</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_424">424</td><td nowrap="nowrap"> :meth:`__del__` method.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_425">425</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_426">426</td><td nowrap="nowrap"> The function is called with a single argument *obj* that identifies the context</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_427">427</td><td nowrap="nowrap"> in which the unraisable exception occurred. The repr of *obj* will be printed in</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_428">428</td><td nowrap="nowrap"> the warning message.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to8__top">t</a></td><td class="diff_header" id="to8_430">430+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_431">431+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_432">432+</td><td nowrap="nowrap"><span class="diff_add">Recursion Control</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_433">433+</td><td nowrap="nowrap"><span class="diff_add">=================</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_434">434+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_435">435+</td><td nowrap="nowrap"><span class="diff_add">These two functions provide a way to perform safe recursive calls at the C</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_436">436+</td><td nowrap="nowrap"><span class="diff_add">level, both in the core and in extension modules. They are needed if the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_437">437+</td><td nowrap="nowrap"><span class="diff_add">recursive code does not necessarily invoke Python code (which tracks its</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_438">438+</td><td nowrap="nowrap"><span class="diff_add">recursion depth automatically).</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_439">439+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_440">440+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: int Py_EnterRecursiveCall(char *where)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_441">441+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_442">442+</td><td nowrap="nowrap"><span class="diff_add"> Marks a point where a recursive C-level call is about to be performed.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_443">443+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_444">444+</td><td nowrap="nowrap"><span class="diff_add"> If :const:`USE_STACKCHECK` is defined, this function checks if the the OS</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_445">445+</td><td nowrap="nowrap"><span class="diff_add"> stack overflowed using :cfunc:`PyOS_CheckStack`. In this is the case, it</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_446">446+</td><td nowrap="nowrap"><span class="diff_add"> sets a :exc:`MemoryError` and returns a nonzero value.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_447">447+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_448">448+</td><td nowrap="nowrap"><span class="diff_add"> The function then checks if the recursion limit is reached. If this is the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_449">449+</td><td nowrap="nowrap"><span class="diff_add"> case, a :exc:`RuntimeError` is set and a nonzero value is returned.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_450">450+</td><td nowrap="nowrap"><span class="diff_add"> Otherwise, zero is returned.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_451">451+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_452">452+</td><td nowrap="nowrap"><span class="diff_add"> *where* should be a string such as ``" in instance check"`` to be</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_453">453+</td><td nowrap="nowrap"><span class="diff_add"> concatenated to the :exc:`RuntimeError` message caused by the recursion depth</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_454">454+</td><td nowrap="nowrap"><span class="diff_add"> limit.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_455">455+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_456">456+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: void Py_LeaveRecursiveCall()</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_457">457+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_458">458+</td><td nowrap="nowrap"><span class="diff_add"> Ends a :cfunc:`Py_EnterRecursiveCall`. Must be called once for each</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to8_459">459+</td><td nowrap="nowrap"><span class="diff_add"> *successful* invocation of :cfunc:`Py_EnterRecursiveCall`.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from8_429">429</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_430">430</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_431">431</td><td nowrap="nowrap">.. _standardexceptions:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_432">432</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_433">433</td><td nowrap="nowrap">Standard Exceptions</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_434">434</td><td nowrap="nowrap">===================</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_435">435</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from8_436">436</td><td nowrap="nowrap">All standard Python exceptions are available as global variables whose names are</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/float.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,38 @@ +--- r262/c-api/float.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/float.rst 2009-10-27 23:34:21.573917000 +0900 +@@ -63,32 +63,32 @@ + without error checking. + + + .. cfunction:: PyObject* PyFloat_GetInfo(void) + + Return a structseq instance which contains information about the + precision, minimum and maximum values of a float. It's a thin wrapper + around the header file :file:`float.h`. + + .. versionadded:: 2.6 + + +-.. cfunction:: double PyFloat_GetMax(void) ++.. cfunction:: double PyFloat_GetMax() + + Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`. + + .. versionadded:: 2.6 + + +-.. cfunction:: double PyFloat_GetMin(void) ++.. cfunction:: double PyFloat_GetMin() + + Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`. + + .. versionadded:: 2.6 + + +-.. cfunction:: int PyFloat_ClearFreeList(void) ++.. cfunction:: int PyFloat_ClearFreeList() + + Clear the float free list. Return the number of items that could not + be freed. + + .. versionadded:: 2.6 ======================================= --- /dev/null +++ /c-api/diff/float.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,54 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to9__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/float.rst => r266/c-api/float.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to9__0"></td><td class="diff_header" id="from9_67">67</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_68">68</td><td nowrap="nowrap"> Return a structseq instance which contains information about the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_69">69</td><td nowrap="nowrap"> precision, minimum and maximum values of a float. It's a thin wrapper</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_70">70</td><td nowrap="nowrap"> around the header file :file:`float.h`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_71">71</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_72">72</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_73">73</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to9__1"></td><td class="diff_header" id="from9_74">74</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to9__1">n</a></td><td class="diff_header" id="from9_75">75-</td><td nowrap="nowrap">.. cfunction:: double PyFloat_GetMax(<span class="diff_sub">void</span>)</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to9__1">n</a></td><td class="diff_header" id="to9_75">75+</td><td nowrap="nowrap">.. cfunction:: double PyFloat_GetMax()</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from9_76">76</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_77">77</td><td nowrap="nowrap"> Return the maximum representable finite float *DBL_MAX* as C :ctype:`double`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_78">78</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_79">79</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_80">80</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to9__2"></td><td class="diff_header" id="from9_81">81</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to9__2">n</a></td><td class="diff_header" id="from9_82">82-</td><td nowrap="nowrap">.. cfunction:: double PyFloat_GetMin(<span class="diff_sub">void</span>)</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to9__2">n</a></td><td class="diff_header" id="to9_82">82+</td><td nowrap="nowrap">.. cfunction:: double PyFloat_GetMin()</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from9_83">83</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_84">84</td><td nowrap="nowrap"> Return the minimum normalized positive float *DBL_MIN* as C :ctype:`double`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_85">85</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_86">86</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_87">87</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_88">88</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to9__top">t</a></td><td class="diff_header" id="from9_89">89-</td><td nowrap="nowrap">.. cfunction:: int PyFloat_ClearFreeList(<span class="diff_sub">void</span>)</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to9__top">t</a></td><td class="diff_header" id="to9_89">89+</td><td nowrap="nowrap">.. cfunction:: int PyFloat_ClearFreeList()</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from9_90">90</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_91">91</td><td nowrap="nowrap"> Clear the float free list. Return the number of items that could not</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_92">92</td><td nowrap="nowrap"> be freed.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_93">93</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from9_94">94</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/gcsupport.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,204 @@ +--- r262/c-api/gcsupport.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/gcsupport.rst 2010-03-22 04:29:04.684594000 +0900 +@@ -1,74 +1,84 @@ + .. highlightlang:: c + + .. _supporting-cycle-detection: + + Supporting Cyclic Garbage Collection + ==================================== + + 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)". + + To create a container type, the :attr:`tp_flags` field of the type object must + include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the + :attr:`tp_traverse` handler. If instances of the type are mutable, a + :attr:`tp_clear` implementation must also be provided. + + + .. 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_NewVar`. + + #. Once all the fields which may contain references to other containers are + initialized, it must call :cfunc:`PyObject_GC_Track`. + + + .. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type) + + Analogous to :cfunc:`PyObject_New` but for container objects with the + :const:`Py_TPFLAGS_HAVE_GC` flag set. + + + .. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size) + + 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) + + A macro version of :cfunc:`PyObject_GC_Track`. It should not be used for + extension modules. + + Similarly, the deallocator for the object must conform to a similar pair of + rules: + + #. Before fields which refer to other containers are invalidated, + :cfunc:`PyObject_GC_UnTrack` must be called. +@@ -76,78 +86,80 @@ + #. The object's memory must be deallocated using :cfunc:`PyObject_GC_Del`. + + + .. cfunction:: void PyObject_GC_Del(void *op) + + Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or + :cfunc:`PyObject_GC_NewVar`. + + + .. 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) + + A macro version of :cfunc:`PyObject_GC_UnTrack`. It should not be used for + extension modules. + + 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: + + + .. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg) + + 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 + 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) + { + Py_VISIT(self->foo); + Py_VISIT(self->bar); + return 0; + } + + .. 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. ======================================= --- /dev/null +++ /c-api/diff/gcsupport.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,134 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to10__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/gcsupport.rst => r266/c-api/gcsupport.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to10__0"></td><td class="diff_header" id="from10_4">4</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_5">5</td><td nowrap="nowrap">Supporting Cyclic Garbage Collection</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_6">6</td><td nowrap="nowrap">====================================</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_7">7</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_8">8</td><td nowrap="nowrap">Python's support for detecting and collecting garbage which involves circular</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_9">9</td><td nowrap="nowrap">references requires support from object types which are "containers" for other</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_10">10</td><td nowrap="nowrap">objects which may also be containers. Types which do not store references to</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_11">11</td><td nowrap="nowrap">other objects, or which only store references to atomic types (such as numbers</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__1">n</a></td><td class="diff_header" id="from10_12">12-</td><td nowrap="nowrap">or strings), do not need to provide any explicit support for garbage<span class="diff_sub"> collection.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__1">n</a></td><td class="diff_header" id="to10_12">12+</td><td nowrap="nowrap">or strings), do not need to provide any explicit support for garbage</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_13">13+</td><td nowrap="nowrap"><span class="diff_add">collection.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_13">13</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_14">14</td><td nowrap="nowrap">.. An example showing the use of these interfaces can be found in "Supporting the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_15">15</td><td nowrap="nowrap">.. Cycle Collector (XXX not found: ../ext/example-cycle-support.html)".</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_16">16</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_17">17</td><td nowrap="nowrap">To create a container type, the :attr:`tp_flags` field of the type object must</td></tr> <tr><td class="diff_next" id="difflib_chg_to10__1"></td><td class="diff_header" id="from10_18">18</td><td nowrap="nowrap">include the :const:`Py_TPFLAGS_HAVE_GC` and provide an implementation of the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_19">19</td><td nowrap="nowrap">:attr:`tp_traverse` handler. If instances of the type are mutable, a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_20">20</td><td nowrap="nowrap">:attr:`tp_clear` implementation must also be provided.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_21">21</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_22">22</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_23">23</td><td nowrap="nowrap">.. data:: Py_TPFLAGS_HAVE_GC</td></tr> <tr><td class="diff_next" id="difflib_chg_to10__2"></td><td class="diff_header" id="from10_24">24</td><td nowrap="nowrap"> :noindex:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_25">25</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__2">n</a></td><td class="diff_header" id="from10_26">26-</td><td nowrap="nowrap"> Objects with a type with this flag set must conform with the rules<span class="diff_sub"> documented</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__2">n</a></td><td class="diff_header" id="to10_27">27+</td><td nowrap="nowrap"> Objects with a type with this flag set must conform with the rules</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_27">27-</td><td nowrap="nowrap"> here. For convenience these objects will be referred to as<span class="diff_sub"> container objects.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_28">28+</td><td nowrap="nowrap"> <span class="diff_add"> documented</span> here. For convenience these objects will be referred to as</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_29">29+</td><td nowrap="nowrap"><span class="diff_add"> container objects.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_28">28</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_29">29</td><td nowrap="nowrap">Constructors for container types must conform to two rules:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_30">30</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__3">n</a></td><td class="diff_header" id="from10_31">31-</td><td nowrap="nowrap">#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New`<span class="diff_sub"> or</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__3">n</a></td><td class="diff_header" id="to10_33">33+</td><td nowrap="nowrap">#. The memory for the object must be allocated using :cfunc:`PyObject_GC_New`</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_32">32-</td><td nowrap="nowrap"> :cfunc:`PyObject_GC_Var<span class="diff_sub">New</span>`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_34">34+</td><td nowrap="nowrap"> <span class="diff_add"> or</span> :cfunc:`PyObject_GC_<span class="diff_add">New</span>Var`.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_33">33</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_34">34</td><td nowrap="nowrap">#. Once all the fields which may contain references to other containers are</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_35">35</td><td nowrap="nowrap"> initialized, it must call :cfunc:`PyObject_GC_Track`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_36">36</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_37">37</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_38">38</td><td nowrap="nowrap">.. cfunction:: TYPE* PyObject_GC_New(TYPE, PyTypeObject *type)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_39">39</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_40">40</td><td nowrap="nowrap"> Analogous to :cfunc:`PyObject_New` but for container objects with the</td></tr> <tr><td class="diff_next" id="difflib_chg_to10__3"></td><td class="diff_header" id="from10_41">41</td><td nowrap="nowrap"> :const:`Py_TPFLAGS_HAVE_GC` flag set.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_42">42</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_43">43</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_44">44</td><td nowrap="nowrap">.. cfunction:: TYPE* PyObject_GC_NewVar(TYPE, PyTypeObject *type, Py_ssize_t size)</td></tr> <tr><td class="diff_next" id="difflib_chg_to10__4"></td><td class="diff_header" id="from10_45">45</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_46">46</td><td nowrap="nowrap"> Analogous to :cfunc:`PyObject_NewVar` but for container objects with the</td></tr> <tr><td class="diff_next" id="difflib_chg_to10__5"></td><td class="diff_header" id="from10_47">47</td><td nowrap="nowrap"> :const:`Py_TPFLAGS_HAVE_GC` flag set.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_48">48</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__4">n</a></td><td class="diff_header" id="to10_51">51+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_52">52+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *size*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_53">53+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_49">49</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__5">n</a></td><td class="diff_header" id="from10_50">50-</td><td nowrap="nowrap"><span class="diff_sub">.. cfunction:: PyVarObject * PyObject_GC_Resize(PyVarObject *op, Py_ssize_t)</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_51">51</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__6">n</a></td><td class="diff_header" id="to10_56">56+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: TYPE* PyObject_GC_Resize(TYPE, PyVarObject *op, Py_ssize_t newsize)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_57">57+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_52">52-</td><td nowrap="nowrap"> Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the<span class="diff_sub"> resized</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_58">58+</td><td nowrap="nowrap"> Resize an object allocated by :cfunc:`PyObject_NewVar`. Returns the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_53">53-</td><td nowrap="nowrap"> object or *NULL* on failure.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_59">59+</td><td nowrap="nowrap"> <span class="diff_add"> resized</span> object or *NULL* on failure.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to10__6"></td><td class="diff_header" id="to10_60">60+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_61">61+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_62">62+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *newsize*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_63">63+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_54">54</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_55">55</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_56">56</td><td nowrap="nowrap">.. cfunction:: void PyObject_GC_Track(PyObject *op)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_57">57</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__7">n</a></td><td class="diff_header" id="from10_58">58-</td><td nowrap="nowrap"> Adds the object *op* to the set of container objects tracked by the<span class="diff_sub"> collector.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__7">n</a></td><td class="diff_header" id="to10_68">68+</td><td nowrap="nowrap"> Adds the object *op* to the set of container objects tracked by the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_59">59-</td><td nowrap="nowrap"> <span class="diff_sub"> The</span> collector can run at unexpected times so objects must be<span class="diff_sub"> valid while being</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_69">69+</td><td nowrap="nowrap"> collector<span class="diff_add">. The collector</span> can run at unexpected times so objects must be</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_60">60-</td><td nowrap="nowrap"> tracked. This should be called once all the fields<span class="diff_sub"> followed by the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_70">70+</td><td nowrap="nowrap"> <span class="diff_add"> valid while being</span> tracked. This should be called once all the fields</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_61">61-</td><td nowrap="nowrap"> :attr:`tp_traverse` handler become valid, usually near the<span class="diff_sub"> end of the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_71">71+</td><td nowrap="nowrap"> <span class="diff_add"> followed by the</span> :attr:`tp_traverse` handler become valid, usually near the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_62">62-</td><td nowrap="nowrap"><span class="diff_sub"> constructor.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_72">72+</td><td nowrap="nowrap"><span class="diff_add"> end of the constructor.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_63">63</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_64">64</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_65">65</td><td nowrap="nowrap">.. cfunction:: void _PyObject_GC_TRACK(PyObject *op)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_66">66</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_67">67</td><td nowrap="nowrap"> A macro version of :cfunc:`PyObject_GC_Track`. It should not be used for</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_68">68</td><td nowrap="nowrap"> extension modules.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_69">69</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_70">70</td><td nowrap="nowrap">Similarly, the deallocator for the object must conform to a similar pair of</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to10__7"></td><td class="diff_header" id="from10_80">80</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_81">81</td><td nowrap="nowrap"> Releases memory allocated to an object using :cfunc:`PyObject_GC_New` or</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_82">82</td><td nowrap="nowrap"> :cfunc:`PyObject_GC_NewVar`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_83">83</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_84">84</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_85">85</td><td nowrap="nowrap">.. cfunction:: void PyObject_GC_UnTrack(void *op)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_86">86</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_87">87</td><td nowrap="nowrap"> Remove the object *op* from the set of container objects tracked by the</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__8">n</a></td><td class="diff_header" id="from10_88">88-</td><td nowrap="nowrap"> collector. Note that :cfunc:`PyObject_GC_Track` can be called again on<span class="diff_sub"> this</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__8">n</a></td><td class="diff_header" id="to10_98">98+</td><td nowrap="nowrap"> collector. Note that :cfunc:`PyObject_GC_Track` can be called again on</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_89">89-</td><td nowrap="nowrap"> object to add it back to the set of tracked objects. The deallocator</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_99">99+</td><td nowrap="nowrap"> <span class="diff_add"> this</span> object to add it back to the set of tracked objects. The deallocator</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_90">90-</td><td nowrap="nowrap"> (:attr:`tp_dealloc` handler) should call this for the object before any of<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_100">100+</td><td nowrap="nowrap"> (:attr:`tp_dealloc` handler) should call this for the object before any of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_91">91-</td><td nowrap="nowrap"> fields used by the :attr:`tp_traverse` handler become invalid.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_101">101+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> fields used by the :attr:`tp_traverse` handler become invalid.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_92">92</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_93">93</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_94">94</td><td nowrap="nowrap">.. cfunction:: void _PyObject_GC_UNTRACK(PyObject *op)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_95">95</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to10__8"></td><td class="diff_header" id="from10_96">96</td><td nowrap="nowrap"> A macro version of :cfunc:`PyObject_GC_UnTrack`. It should not be used for</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_97">97</td><td nowrap="nowrap"> extension modules.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_98">98</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_99">99</td><td nowrap="nowrap">The :attr:`tp_traverse` handler accepts a function parameter of this type:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_100">100</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_101">101</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_102">102</td><td nowrap="nowrap">.. ctype:: int (*visitproc)(PyObject *object, void *arg)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_103">103</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__9">n</a></td><td class="diff_header" id="from10_104">104-</td><td nowrap="nowrap"> Type of the visitor function passed to the :attr:`tp_traverse` handler.<span class="diff_sub"> The</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__9">n</a></td><td class="diff_header" id="to10_114">114+</td><td nowrap="nowrap"> Type of the visitor function passed to the :attr:`tp_traverse` handler.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_105">105-</td><td nowrap="nowrap"> function should be called with an object to traverse as *object* and<span class="diff_sub"> the third</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_115">115+</td><td nowrap="nowrap"> <span class="diff_add"> The</span> function should be called with an object to traverse as *object* and</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_106">106-</td><td nowrap="nowrap"> parameter to the :attr:`tp_traverse` handler as *arg*. The<span class="diff_sub"> Python core uses</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_116">116+</td><td nowrap="nowrap"> <span class="diff_add"> the third</span> parameter to the :attr:`tp_traverse` handler as *arg*. The</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_107">107-</td><td nowrap="nowrap"> several visitor functions to implement cyclic garbage<span class="diff_sub"> detection; it's not</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_117">117+</td><td nowrap="nowrap"> <span class="diff_add"> Python core uses</span> several visitor functions to implement cyclic garbage</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_108">108-</td><td nowrap="nowrap"><span class="diff_sub"> expected that users will need to write their own visitor functions.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_118">118+</td><td nowrap="nowrap"><span class="diff_add"> detection; it's not expected that users will need to write their own</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_119">119+</td><td nowrap="nowrap"><span class="diff_add"> visitor functions.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to10__9"></td><td class="diff_header" id="from10_109">109</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_110">110</td><td nowrap="nowrap">The :attr:`tp_traverse` handler must have the following type:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_111">111</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_112">112</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_113">113</td><td nowrap="nowrap">.. ctype:: int (*traverseproc)(PyObject *self, visitproc visit, void *arg)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_114">114</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_115">115</td><td nowrap="nowrap"> Traversal function for a container object. Implementations must call the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_116">116</td><td nowrap="nowrap"> *visit* function for each object directly contained by *self*, with the</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__10">n</a></td><td class="diff_header" id="from10_117">117-</td><td nowrap="nowrap"> parameters to *visit* being the contained object and the *arg* value passed<span class="diff_sub"> to</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__10">n</a></td><td class="diff_header" id="to10_128">128+</td><td nowrap="nowrap"> parameters to *visit* being the contained object and the *arg* value passed</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_118">118-</td><td nowrap="nowrap"> the handler. The *visit* function must not be called with a *NULL*<span class="diff_sub"> object</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_129">129+</td><td nowrap="nowrap"> <span class="diff_add"> to</span> the handler. The *visit* function must not be called with a *NULL*</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_119">119-</td><td nowrap="nowrap"> argument. If *visit* returns a non-zero value that value should be<span class="diff_sub"> returned</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_130">130+</td><td nowrap="nowrap"> <span class="diff_add"> object</span> argument. If *visit* returns a non-zero value that value should be</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_120">120-</td><td nowrap="nowrap"> immediately.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_131">131+</td><td nowrap="nowrap"> <span class="diff_add"> returned</span> immediately.</td></tr> + <tr><td class="diff_next" id="difflib_chg_to10__10"></td><td class="diff_header" id="from10_121">121</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_122">122</td><td nowrap="nowrap">To simplify writing :attr:`tp_traverse` handlers, a :cfunc:`Py_VISIT` macro is</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_123">123</td><td nowrap="nowrap">provided. In order to use this macro, the :attr:`tp_traverse` implementation</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_124">124</td><td nowrap="nowrap">must name its arguments exactly *visit* and *arg*:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_125">125</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_126">126</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_127">127</td><td nowrap="nowrap">.. cfunction:: void Py_VISIT(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_128">128</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__11">n</a></td><td class="diff_header" id="from10_129">129-</td><td nowrap="nowrap"> Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns<span class="diff_sub"> a</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__11">n</a></td><td class="diff_header" id="to10_140">140+</td><td nowrap="nowrap"> Call the *visit* callback, with arguments *o* and *arg*. If *visit* returns</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_130">130-</td><td nowrap="nowrap"> non-zero value, then return it. Using this macro, :attr:`tp_traverse`<span class="diff_sub"> handlers</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_141">141+</td><td nowrap="nowrap"> <span class="diff_add"> a</span> non-zero value, then return it. Using this macro, :attr:`tp_traverse`</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_131">131-</td><td nowrap="nowrap"> look like::</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_142">142+</td><td nowrap="nowrap"> <span class="diff_add"> handlers</span> look like::</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_132">132</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_133">133</td><td nowrap="nowrap"> static int</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_134">134</td><td nowrap="nowrap"> my_traverse(Noddy *self, visitproc visit, void *arg)</td></tr> <tr><td class="diff_next" id="difflib_chg_to10__11"></td><td class="diff_header" id="from10_135">135</td><td nowrap="nowrap"> {</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_136">136</td><td nowrap="nowrap"> Py_VISIT(self->foo);</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_137">137</td><td nowrap="nowrap"> Py_VISIT(self->bar);</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_138">138</td><td nowrap="nowrap"> return 0;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_139">139</td><td nowrap="nowrap"> }</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_140">140</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to10__12"></td><td class="diff_header" id="from10_141">141</td><td nowrap="nowrap"> .. versionadded:: 2.4</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_142">142</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__12">n</a></td><td class="diff_header" id="from10_143">143-</td><td nowrap="nowrap">The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL*<span class="diff_sub"> if</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__12">n</a></td><td class="diff_header" id="to10_154">154+</td><td nowrap="nowrap">The :attr:`tp_clear` handler must be of the :ctype:`inquiry` type, or *NULL*</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_144">144-</td><td nowrap="nowrap">the object is immutable.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_155">155+</td><td nowrap="nowrap"><span class="diff_add">if </span>the object is immutable.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from10_145">145</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_146">146</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_147">147</td><td nowrap="nowrap">.. ctype:: int (*inquiry)(PyObject *self)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from10_148">148</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to10__top">t</a></td><td class="diff_header" id="from10_149">149-</td><td nowrap="nowrap"> Drop references that may have created reference cycles. Immutable objects<span class="diff_sub"> do</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to10__top">t</a></td><td class="diff_header" id="to10_160">160+</td><td nowrap="nowrap"> Drop references that may have created reference cycles. Immutable objects</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_150">150-</td><td nowrap="nowrap"> not have to define this method since they can never directly create<span class="diff_sub"> reference</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_161">161+</td><td nowrap="nowrap"> <span class="diff_add"> do</span> not have to define this method since they can never directly create</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_151">151-</td><td nowrap="nowrap"> cycles. Note that the object must still be valid after calling<span class="diff_sub"> this method</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_162">162+</td><td nowrap="nowrap"> <span class="diff_add"> reference</span> cycles. Note that the object must still be valid after calling</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_152">152-</td><td nowrap="nowrap"> (don't just call :cfunc:`Py_DECREF` on a reference). The<span class="diff_sub"> collector will call</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_163">163+</td><td nowrap="nowrap"> <span class="diff_add"> this method</span> (don't just call :cfunc:`Py_DECREF` on a reference). The</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from10_153">153-</td><td nowrap="nowrap"><span class="diff_sub"> this method if it detects that this object is involved in a reference cycle.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_164">164+</td><td nowrap="nowrap"><span class="diff_add"> collector will call this method if it detects that this object is involved</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to10_165">165+</td><td nowrap="nowrap"><span class="diff_add"> in a reference cycle.</span></td></tr> + </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/import.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,152 @@ +--- r262/c-api/import.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/import.rst 2010-05-19 08:13:04.544632000 +0900 +@@ -19,28 +19,28 @@ + argument contains a dot (when it specifies a submodule of a package), the + *fromlist* argument is set to the list ``['*']`` so that the return value is the + named module rather than the top-level package containing it as would otherwise + be the case. (Unfortunately, this has an additional side effect when *name* in + fact specifies a subpackage instead of a submodule: the submodules specified in + the package's ``__all__`` variable are loaded.) Return a new reference to the + imported module, or *NULL* with an exception set on failure. Before Python 2.4, + the module may still be created in the failure case --- examine ``sys.modules`` + to find out. Starting with Python 2.4, a failing import of a module no longer + leaves the module in ``sys.modules``. + + .. versionchanged:: 2.4 +- failing imports remove incomplete module objects. ++ Failing imports remove incomplete module objects. + + .. versionchanged:: 2.6 +- always use absolute imports ++ Always uses absolute imports. + + + .. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name) + + This version of :cfunc:`PyImport_ImportModule` does not block. It's intended + to be used in C functions that import other modules to execute a function. + The import may block if another thread holds the import lock. The function + :cfunc:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch + the module from sys.modules and falls back to :cfunc:`PyImport_ImportModule` + unless the lock is held, in which case the function will raise an + :exc:`ImportError`. + +@@ -53,25 +53,25 @@ + + Import a module. This is best described by referring to the built-in Python + function :func:`__import__`, as the standard :func:`__import__` function calls + this function directly. + + The return value is a new reference to the imported module or top-level package, + or *NULL* with an exception set on failure (before Python 2.4, the module may + still be created in this case). Like for :func:`__import__`, the return value + when a submodule of a package was requested is normally the top-level package, + unless a non-empty *fromlist* was given. + + .. versionchanged:: 2.4 +- failing imports remove incomplete module objects. ++ Failing imports remove incomplete module objects. + + .. versionchanged:: 2.6 + The function is an alias for :cfunc:`PyImport_ImportModuleLevel` with + -1 as level, meaning relative import. + + + .. cfunction:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level) + + Import a module. This is best described by referring to the built-in Python + function :func:`__import__`, as the standard :func:`__import__` function calls + this function directly. + +@@ -86,25 +86,25 @@ + .. cfunction:: PyObject* PyImport_Import(PyObject *name) + + .. index:: + module: rexec + module: ihooks + + This is a higher-level interface that calls the current "import hook function". + It invokes the :func:`__import__` function from the ``__builtins__`` of the + current globals. This means that the import is done using whatever import hooks + are installed in the current environment, e.g. by :mod:`rexec` or :mod:`ihooks`. + + .. versionchanged:: 2.6 +- always use absolute imports ++ Always uses absolute imports. + + + .. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m) + + .. index:: builtin: reload + + Reload a module. This is best described by referring to the built-in Python + function :func:`reload`, as the standard :func:`reload` function calls this + function directly. Return a new reference to the reloaded module, or *NULL* + with an exception set on failure (the module still exists in this case). + + +@@ -129,54 +129,63 @@ + + Given a module name (possibly of the form ``package.module``) and a code object + read from a Python bytecode file or obtained from the built-in function + :func:`compile`, load the module. Return a new reference to the module object, + or *NULL* with an exception set if an error occurred. Before Python 2.4, the + module could still be created in error cases. Starting with Python 2.4, *name* + is removed from :attr:`sys.modules` in error cases, and even if *name* was already + in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`. Leaving + incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of + such modules have no way to know that the module object is an unknown (and + probably damaged with respect to the module author's intents) state. + ++ The module's :attr:`__file__` attribute will be set to the code object's ++ :cmember:`co_filename`. ++ + This function will reload the module if it was already imported. See + :cfunc:`PyImport_ReloadModule` for the intended way to reload a module. + + If *name* points to a dotted name of the form ``package.module``, any package + structures not already created will still not be created. + + .. versionchanged:: 2.4 + *name* is removed from :attr:`sys.modules` in error cases. + + ++.. cfunction:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname) ++ ++ Like :cfunc:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of ++ the module object is set to *pathname* if it is non-``NULL``. ++ ++ + .. cfunction:: long PyImport_GetMagicNumber() + + Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and + :file:`.pyo` files). The magic number should be present in the first four bytes + of the bytecode file, in little-endian byte order. + + + .. cfunction:: PyObject* PyImport_GetModuleDict() + + Return the dictionary used for the module administration (a.k.a. + ``sys.modules``). Note that this is a per-interpreter variable. + + + .. cfunction:: PyObject* PyImport_GetImporter(PyObject *path) + + Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item + *path*, possibly by fetching it from the :data:`sys.path_importer_cache` + dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook + is found that can handle the path item. Return ``None`` if no hook could; +- this tells our caller it should fall back to the builtin import mechanism. ++ this tells our caller it should fall back to the built-in import mechanism. + Cache the result in :data:`sys.path_importer_cache`. Return a new reference + to the importer object. + + .. versionadded:: 2.6 + + + .. cfunction:: void _PyImport_Init() + + Initialize the import mechanism. For internal use only. + + + .. cfunction:: void PyImport_Cleanup() ======================================= --- /dev/null +++ /c-api/diff/import.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,75 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to11__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/import.rst => r266/c-api/import.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to11__0"></td><td class="diff_header" id="from11_23">23</td><td nowrap="nowrap"> fact specifies a subpackage instead of a submodule: the submodules specified in</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_24">24</td><td nowrap="nowrap"> the package's ``__all__`` variable are loaded.) Return a new reference to the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_25">25</td><td nowrap="nowrap"> imported module, or *NULL* with an exception set on failure. Before Python 2.4,</td></tr> <tr><td class="diff_next" id="difflib_chg_to11__1"></td><td class="diff_header" id="from11_26">26</td><td nowrap="nowrap"> the module may still be created in the failure case --- examine ``sys.modules``</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_27">27</td><td nowrap="nowrap"> to find out. Starting with Python 2.4, a failing import of a module no longer</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_28">28</td><td nowrap="nowrap"> leaves the module in ``sys.modules``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_29">29</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_30">30</td><td nowrap="nowrap"> .. versionchanged:: 2.4</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to11__1">n</a></td><td class="diff_header" id="from11_31">31-</td><td nowrap="nowrap"> <span class="diff_chg">f</span>ailing imports remove incomplete module objects.</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to11__1">n</a></td><td class="diff_header" id="to11_31">31+</td><td nowrap="nowrap"> <span class="diff_chg">F</span>ailing imports remove incomplete module objects.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from11_32">32</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_33">33</td><td nowrap="nowrap"> .. versionchanged:: 2.6</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to11__2">n</a></td><td class="diff_header" id="from11_34">34-</td><td nowrap="nowrap"> <span class="diff_chg">a</span>lways use absolute imports</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to11__2">n</a></td><td class="diff_header" id="to11_34">34+</td><td nowrap="nowrap"> <span class="diff_chg">A</span>lways use<span class="diff_add">s</span> absolute imports<span class="diff_add">.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from11_35">35</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_36">36</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_37">37</td><td nowrap="nowrap">.. cfunction:: PyObject* PyImport_ImportModuleNoBlock(const char *name)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_38">38</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_39">39</td><td nowrap="nowrap"> This version of :cfunc:`PyImport_ImportModule` does not block. It's intended</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_40">40</td><td nowrap="nowrap"> to be used in C functions that import other modules to execute a function.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_41">41</td><td nowrap="nowrap"> The import may block if another thread holds the import lock. The function</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_42">42</td><td nowrap="nowrap"> :cfunc:`PyImport_ImportModuleNoBlock` never blocks. It first tries to fetch</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to11__2"></td><td class="diff_header" id="from11_57">57</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_58">58</td><td nowrap="nowrap"> The return value is a new reference to the imported module or top-level package,</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_59">59</td><td nowrap="nowrap"> or *NULL* with an exception set on failure (before Python 2.4, the module may</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_60">60</td><td nowrap="nowrap"> still be created in this case). Like for :func:`__import__`, the return value</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_61">61</td><td nowrap="nowrap"> when a submodule of a package was requested is normally the top-level package,</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_62">62</td><td nowrap="nowrap"> unless a non-empty *fromlist* was given.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_63">63</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_64">64</td><td nowrap="nowrap"> .. versionchanged:: 2.4</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to11__3">n</a></td><td class="diff_header" id="from11_65">65-</td><td nowrap="nowrap"> <span class="diff_chg">f</span>ailing imports remove incomplete module objects.</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to11__3">n</a></td><td class="diff_header" id="to11_65">65+</td><td nowrap="nowrap"> <span class="diff_chg">F</span>ailing imports remove incomplete module objects.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from11_66">66</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_67">67</td><td nowrap="nowrap"> .. versionchanged:: 2.6</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_68">68</td><td nowrap="nowrap"> The function is an alias for :cfunc:`PyImport_ImportModuleLevel` with</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_69">69</td><td nowrap="nowrap"> -1 as level, meaning relative import.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_70">70</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_71">71</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_72">72</td><td nowrap="nowrap">.. cfunction:: PyObject* PyImport_ImportModuleLevel(char *name, PyObject *globals, PyObject *locals, PyObject *fromlist, int level)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_73">73</td><td nowrap="nowrap"></td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to11__3"></td><td class="diff_header" id="from11_90">90</td><td nowrap="nowrap"> module: ihooks</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_91">91</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_92">92</td><td nowrap="nowrap"> This is a higher-level interface that calls the current "import hook function".</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_93">93</td><td nowrap="nowrap"> It invokes the :func:`__import__` function from the ``__builtins__`` of the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_94">94</td><td nowrap="nowrap"> current globals. This means that the import is done using whatever import hooks</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_95">95</td><td nowrap="nowrap"> are installed in the current environment, e.g. by :mod:`rexec` or :mod:`ihooks`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_96">96</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_97">97</td><td nowrap="nowrap"> .. versionchanged:: 2.6</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to11__4">n</a></td><td class="diff_header" id="from11_98">98-</td><td nowrap="nowrap"> <span class="diff_chg">a</span>lways use absolute imports</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to11__4">n</a></td><td class="diff_header" id="to11_98">98+</td><td nowrap="nowrap"> <span class="diff_chg">A</span>lways use<span class="diff_add">s</span> absolute imports<span class="diff_add">.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from11_99">99</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_100">100</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_101">101</td><td nowrap="nowrap">.. cfunction:: PyObject* PyImport_ReloadModule(PyObject *m)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_102">102</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_103">103</td><td nowrap="nowrap"> .. index:: builtin: reload</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_104">104</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_105">105</td><td nowrap="nowrap"> Reload a module. This is best described by referring to the built-in Python</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_106">106</td><td nowrap="nowrap"> function :func:`reload`, as the standard :func:`reload` function calls this</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to11__4"></td><td class="diff_header" id="from11_133">133</td><td nowrap="nowrap"> or *NULL* with an exception set if an error occurred. Before Python 2.4, the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_134">134</td><td nowrap="nowrap"> module could still be created in error cases. Starting with Python 2.4, *name*</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_135">135</td><td nowrap="nowrap"> is removed from :attr:`sys.modules` in error cases, and even if *name* was already</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_136">136</td><td nowrap="nowrap"> in :attr:`sys.modules` on entry to :cfunc:`PyImport_ExecCodeModule`. Leaving</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_137">137</td><td nowrap="nowrap"> incompletely initialized modules in :attr:`sys.modules` is dangerous, as imports of</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_138">138</td><td nowrap="nowrap"> such modules have no way to know that the module object is an unknown (and</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_139">139</td><td nowrap="nowrap"> probably damaged with respect to the module author's intents) state.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_140">140</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to11__5">n</a></td><td class="diff_header" id="to11_141">141+</td><td nowrap="nowrap"><span class="diff_add"> The module's :attr:`__file__` attribute will be set to the code object's</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to11_142">142+</td><td nowrap="nowrap"><span class="diff_add"> :cmember:`co_filename`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to11_143">143+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to11__5"></td><td class="diff_header" id="from11_141">141</td><td nowrap="nowrap"> This function will reload the module if it was already imported. See</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_142">142</td><td nowrap="nowrap"> :cfunc:`PyImport_ReloadModule` for the intended way to reload a module.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_143">143</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_144">144</td><td nowrap="nowrap"> If *name* points to a dotted name of the form ``package.module``, any package</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_145">145</td><td nowrap="nowrap"> structures not already created will still not be created.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_146">146</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_147">147</td><td nowrap="nowrap"> .. versionchanged:: 2.4</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_148">148</td><td nowrap="nowrap"> *name* is removed from :attr:`sys.modules` in error cases.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to11__6">n</a></td><td class="diff_header" id="to11_152">152+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to11_153">153+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to11_154">154+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: PyObject* PyImport_ExecCodeModuleEx(char *name, PyObject *co, char *pathname)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to11_155">155+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to11_156">156+</td><td nowrap="nowrap"><span class="diff_add"> Like :cfunc:`PyImport_ExecCodeModule`, but the :attr:`__file__` attribute of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to11_157">157+</td><td nowrap="nowrap"><span class="diff_add"> the module object is set to *pathname* if it is non-``NULL``.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from11_149">149</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_150">150</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_151">151</td><td nowrap="nowrap">.. cfunction:: long PyImport_GetMagicNumber()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_152">152</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_153">153</td><td nowrap="nowrap"> Return the magic number for Python bytecode files (a.k.a. :file:`.pyc` and</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_154">154</td><td nowrap="nowrap"> :file:`.pyo` files). The magic number should be present in the first four bytes</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_155">155</td><td nowrap="nowrap"> of the bytecode file, in little-endian byte order.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_156">156</td><td nowrap="nowrap"></td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to11__6"></td><td class="diff_header" id="from11_162">162</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_163">163</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_164">164</td><td nowrap="nowrap">.. cfunction:: PyObject* PyImport_GetImporter(PyObject *path)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_165">165</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_166">166</td><td nowrap="nowrap"> Return an importer object for a :data:`sys.path`/:attr:`pkg.__path__` item</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_167">167</td><td nowrap="nowrap"> *path*, possibly by fetching it from the :data:`sys.path_importer_cache`</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_168">168</td><td nowrap="nowrap"> dict. If it wasn't yet cached, traverse :data:`sys.path_hooks` until a hook</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_169">169</td><td nowrap="nowrap"> is found that can handle the path item. Return ``None`` if no hook could;</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to11__top">t</a></td><td class="diff_header" id="from11_170">170-</td><td nowrap="nowrap"> this tells our caller it should fall back to the builtin import mechanism.</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to11__top">t</a></td><td class="diff_header" id="to11_179">179+</td><td nowrap="nowrap"> this tells our caller it should fall back to the built<span class="diff_add">-</span>in import mechanism.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from11_171">171</td><td nowrap="nowrap"> Cache the result in :data:`sys.path_importer_cache`. Return a new reference</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_172">172</td><td nowrap="nowrap"> to the importer object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_173">173</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_174">174</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_175">175</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_176">176</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_177">177</td><td nowrap="nowrap">.. cfunction:: void _PyImport_Init()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from11_178">178</td><td nowrap="nowrap"></td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/init.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,305 @@ +--- r262/c-api/init.rst 2009-04-06 06:26:31.956399000 +0900 ++++ r266/c-api/init.rst 2010-05-22 02:22:43.998748000 +0900 +@@ -13,34 +13,35 @@ + .. index:: + single: Py_SetProgramName() + single: PyEval_InitThreads() + single: PyEval_ReleaseLock() + single: PyEval_AcquireLock() + single: modules (in module sys) + single: path (in module sys) + module: __builtin__ + module: __main__ + module: sys + triple: module; search; path + single: PySys_SetArgv() ++ single: PySys_SetArgvEx() + single: Py_Finalize() + + Initialize the Python interpreter. In an application embedding Python, this + should be called before using any other Python/C API functions; with the + exception of :cfunc:`Py_SetProgramName`, :cfunc:`PyEval_InitThreads`, + :cfunc:`PyEval_ReleaseLock`, and :cfunc:`PyEval_AcquireLock`. This initializes + the table of loaded modules (``sys.modules``), and creates the fundamental + modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. It also initializes + the module search path (``sys.path``). It does not set ``sys.argv``; use +- :cfunc:`PySys_SetArgv` for that. This is a no-op when called for a second time ++ :cfunc:`PySys_SetArgvEx` for that. This is a no-op when called for a second time + (without calling :cfunc:`Py_Finalize` first). There is no return value; it is a + fatal error if the initialization fails. + + + .. cfunction:: void Py_InitializeEx(int initsigs) + + This function works like :cfunc:`Py_Initialize` if *initsigs* is 1. If + *initsigs* is 0, it skips initialization registration of signal handlers, which + might be useful when Python is embedded. + + .. versionadded:: 2.4 + +@@ -248,60 +249,52 @@ + side-effect of deriving the default module search path from the program name + (set by :cfunc:`Py_SetProgramName` above). The returned string points into + static storage; the caller should not modify its value. The value is available + to Python code as ``sys.executable``. + + + .. cfunction:: char* Py_GetPath() + + .. index:: + triple: module; search; path + single: path (in module sys) + +- Return the default module search path; this is computed from the program name +- (set by :cfunc:`Py_SetProgramName` above) and some environment variables. The +- returned string consists of a series of directory names separated by a platform +- dependent delimiter character. The delimiter character is ``':'`` on Unix and +- Mac OS X, ``';'`` on Windows. The returned string points into static storage; +- the caller should not modify its value. The value is available to Python code +- as the list ``sys.path``, which may be modified to change the future search path +- for loaded modules. ++ Return the default module search path; this is computed from the program name ++ (set by :cfunc:`Py_SetProgramName` above) and some environment variables. ++ The returned string consists of a series of directory names separated by a ++ platform dependent delimiter character. The delimiter character is ``':'`` ++ on Unix and Mac OS X, ``';'`` on Windows. The returned string points into ++ static storage; the caller should not modify its value. The list ++ :data:`sys.path` is initialized with this value on interpreter startup; it ++ can be (and usually is) modified later to change the search path for loading ++ modules. + + .. XXX should give the exact rules + + + .. cfunction:: const char* Py_GetVersion() + + Return the version of this Python interpreter. This is a string that looks + something like :: + + "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]" + + .. index:: single: version (in module sys) + + The first word (up to the first space character) is the current Python version; + the first three characters are the major and minor version separated by a + period. The returned string points into static storage; the caller should not + modify its value. The value is available to Python code as ``sys.version``. + + +-.. cfunction:: const char* Py_GetBuildNumber() +- +- Return a string representing the Subversion revision that this Python executable +- was built from. This number is a string because it may contain a trailing 'M' +- if Python was built from a mixed revision source tree. +- +- .. versionadded:: 2.5 +- +- + .. cfunction:: const char* Py_GetPlatform() + + .. index:: single: platform (in module sys) + + Return the platform identifier for the current platform. On Unix, this is + formed from the "official" name of the operating system, converted to lower + case, followed by the major revision number; e.g., for Solaris 2.x, which is + also known as SunOS 5.x, the value is ``'sunos5'``. On Mac OS X, it is + ``'darwin'``. On Windows, it is ``'win'``. The returned string points into + static storage; the caller should not modify its value. The value is available + to Python code as ``sys.platform``. + +@@ -337,52 +330,83 @@ + Return information about the sequence number and build date and time of the + current Python interpreter instance, for example :: + + "#67, Aug 1 1997, 22:34:28" + + .. index:: single: version (in module sys) + + The returned string points into static storage; the caller should not modify its + value. The value is available to Python code as part of the variable + ``sys.version``. + + +-.. cfunction:: void PySys_SetArgv(int argc, char **argv) ++.. cfunction:: void PySys_SetArgvEx(int argc, char **argv, int updatepath) + + .. index:: + single: main() + single: Py_FatalError() + single: argv (in module sys) + + Set :data:`sys.argv` based on *argc* and *argv*. These parameters are + similar to those passed to the program's :cfunc:`main` function with the + difference that the first entry should refer to the script file to be + executed rather than the executable hosting the Python interpreter. If there + isn't a script that will be run, the first entry in *argv* can be an empty + string. If this function fails to initialize :data:`sys.argv`, a fatal + condition is signalled using :cfunc:`Py_FatalError`. + +- This function also prepends the executed script's path to :data:`sys.path`. +- If no script is executed (in the case of calling ``python -c`` or just the +- interactive interpreter), the empty string is used instead. ++ If *updatepath* is zero, this is all the function does. If *updatepath* ++ is non-zero, the function also modifies :data:`sys.path` according to the ++ following algorithm: ++ ++ - If the name of an existing script is passed in ``argv[0]``, the absolute ++ path of the directory where the script is located is prepended to ++ :data:`sys.path`. ++ - Otherwise (that is, if *argc* is 0 or ``argv[0]`` doesn't point ++ to an existing file name), an empty string is prepended to ++ :data:`sys.path`, which is the same as prepending the current working ++ directory (``"."``). ++ ++ .. note:: ++ It is recommended that applications embedding the Python interpreter ++ for purposes other than executing a single script pass 0 as *updatepath*, ++ and update :data:`sys.path` themselves if desired. ++ See `CVE-2008-5983 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_. ++ ++ On versions before 2.6.6, you can achieve the same effect by manually ++ popping the first :data:`sys.path` element after having called ++ :cfunc:`PySys_SetArgv`, for example using:: ++ ++ PyRun_SimpleString("import sys; sys.path.pop(0)\n"); ++ ++ .. versionadded:: 2.6.6 + + .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params; + check w/ Guido. + + ++.. cfunction:: void PySys_SetArgv(int argc, char **argv) ++ ++ This function works like :cfunc:`PySys_SetArgv` with *updatepath* set to 1. ++ ++ + .. cfunction:: void Py_SetPythonHome(char *home) + + Set the default "home" directory, that is, the location of the standard + Python libraries. The libraries are searched in + :file:`{home}/lib/python{version}` and :file:`{home}/lib/python{version}`. ++ The argument should point to a zero-terminated character string in static ++ storage whose contents will not change for the duration of the program's ++ execution. No code in the Python interpreter will change the contents of ++ this storage. + + + .. cfunction:: char* Py_GetPythonHome() + + Return the default "home", that is, the value set by a previous call to + :cfunc:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME` + environment variable if it is set. + + + .. _threads: + + Thread State and the Global Interpreter Lock +@@ -410,28 +434,27 @@ + (this can be changed with :func:`sys.setcheckinterval`). The lock is also + released and reacquired around potentially blocking I/O operations like reading + or writing a file, so that other threads can run while the thread that requests + the I/O is waiting for the I/O operation to complete. + + .. index:: + single: PyThreadState + single: PyThreadState + + The Python interpreter needs to keep some bookkeeping information separate per + thread --- for this it uses a data structure called :ctype:`PyThreadState`. + There's one global variable, however: the pointer to the current +-:ctype:`PyThreadState` structure. While most thread packages have a way to +-store "per-thread global data," Python's internal platform independent thread +-abstraction doesn't support this yet. Therefore, the current thread state must +-be manipulated explicitly. ++:ctype:`PyThreadState` structure. Before the addition of :dfn:`thread-local ++storage` (:dfn:`TLS`) the current thread state had to be manipulated ++explicitly. + + This is easy enough in most cases. Most code manipulating the global + interpreter lock has the following simple structure:: + + Save the thread state in a local variable. + Release the global interpreter lock. + ...Do some blocking I/O operation... + Reacquire the global interpreter lock. + Restore the thread state from the local variable. + + This is so common that a pair of macros exists to simplify it:: + +@@ -483,52 +506,68 @@ + :cfunc:`PyEval_ReleaseLock` and :cfunc:`PyEval_AcquireLock` are not available. + This is done so that dynamically loaded extensions compiled with thread support + enabled can be loaded by an interpreter that was compiled with disabled thread + support. + + The global interpreter lock is used to protect the pointer to the current thread + state. When releasing the lock and saving the thread state, the current thread + state pointer must be retrieved before the lock is released (since another + 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 + typical idiom for calling into Python from a C thread is now:: + + PyGILState_STATE gstate; + gstate = PyGILState_Ensure(); + + /* Perform Python actions here. */ + result = CallSomeFunction(); + /* evaluate result */ + + /* Release the thread. No Python API allowed beyond this point. */ + PyGILState_Release(gstate); + + Note that the :cfunc:`PyGILState_\*` functions assume there is only one global + interpreter (created automatically by :cfunc:`Py_Initialize`). Python still + supports the creation of additional interpreters (using + :cfunc:`Py_NewInterpreter`), but mixing multiple interpreters and the + :cfunc:`PyGILState_\*` API is unsupported. + ++Another important thing to note about threads is their behaviour in the face ++of the C :cfunc:`fork` call. On most systems with :cfunc:`fork`, after a ++process forks only the thread that issued the fork will exist. That also ++means any locks held by other threads will never be released. Python solves ++this for :func:`os.fork` by acquiring the locks it uses internally before ++the fork, and releasing them afterwards. In addition, it resets any ++:ref:`lock-objects` in the child. When extending or embedding Python, there ++is no way to inform Python of additional (non-Python) locks that need to be ++acquired before or reset after a fork. OS facilities such as ++:cfunc:`posix_atfork` would need to be used to accomplish the same thing. ++Additionally, when extending or embedding Python, calling :cfunc:`fork` ++directly rather than through :func:`os.fork` (and returning to or calling ++into Python) may result in a deadlock by one of Python's internal locks ++being held by a thread that is defunct after the fork. ++:cfunc:`PyOS_AfterFork` tries to reset the necessary locks, but is not ++always able to. + + .. ctype:: PyInterpreterState + + This data structure represents the state shared by a number of cooperating + threads. Threads belonging to the same interpreter share their module + administration and a few other internal items. There are no public members in + this structure. + + Threads belonging to different interpreters initially share nothing, except + process state like available memory, open file descriptors and such. The global + interpreter lock is also shared by all threads, regardless of to which + interpreter they belong. ======================================= --- /dev/null +++ /c-api/diff/init.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,165 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to12__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/init.rst => r266/c-api/init.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to12__0"></td><td class="diff_header" id="from12_17">17</td><td nowrap="nowrap"> single: PyEval_AcquireLock()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_18">18</td><td nowrap="nowrap"> single: modules (in module sys)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_19">19</td><td nowrap="nowrap"> single: path (in module sys)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_20">20</td><td nowrap="nowrap"> module: __builtin__</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_21">21</td><td nowrap="nowrap"> module: __main__</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_22">22</td><td nowrap="nowrap"> module: sys</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_23">23</td><td nowrap="nowrap"> triple: module; search; path</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_24">24</td><td nowrap="nowrap"> single: PySys_SetArgv()</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__1">n</a></td><td class="diff_header" id="to12_25">25+</td><td nowrap="nowrap"><span class="diff_add"> single: PySys_SetArgvEx()</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_25">25</td><td nowrap="nowrap"> single: Py_Finalize()</td></tr> <tr><td class="diff_next" id="difflib_chg_to12__1"></td><td class="diff_header" id="from12_26">26</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_27">27</td><td nowrap="nowrap"> Initialize the Python interpreter. In an application embedding Python, this</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_28">28</td><td nowrap="nowrap"> should be called before using any other Python/C API functions; with the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_29">29</td><td nowrap="nowrap"> exception of :cfunc:`Py_SetProgramName`, :cfunc:`PyEval_InitThreads`,</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_30">30</td><td nowrap="nowrap"> :cfunc:`PyEval_ReleaseLock`, and :cfunc:`PyEval_AcquireLock`. This initializes</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_31">31</td><td nowrap="nowrap"> the table of loaded modules (``sys.modules``), and creates the fundamental</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_32">32</td><td nowrap="nowrap"> modules :mod:`__builtin__`, :mod:`__main__` and :mod:`sys`. It also initializes</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_33">33</td><td nowrap="nowrap"> the module search path (``sys.path``). It does not set ``sys.argv``; use</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__2">n</a></td><td class="diff_header" id="from12_34">34-</td><td nowrap="nowrap"> :cfunc:`PySys_SetArgv` for that. This is a no-op when called for a second time</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to12__2">n</a></td><td class="diff_header" id="to12_35">35+</td><td nowrap="nowrap"> :cfunc:`PySys_SetArgv<span class="diff_add">Ex</span>` for that. This is a no-op when called for a second time</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_35">35</td><td nowrap="nowrap"> (without calling :cfunc:`Py_Finalize` first). There is no return value; it is a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_36">36</td><td nowrap="nowrap"> fatal error if the initialization fails.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_37">37</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_38">38</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_39">39</td><td nowrap="nowrap">.. cfunction:: void Py_InitializeEx(int initsigs)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_40">40</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_41">41</td><td nowrap="nowrap"> This function works like :cfunc:`Py_Initialize` if *initsigs* is 1. If</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_42">42</td><td nowrap="nowrap"> *initsigs* is 0, it skips initialization registration of signal handlers, which</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to12__2"></td><td class="diff_header" id="from12_252">252</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_253">253</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_254">254</td><td nowrap="nowrap">.. cfunction:: char* Py_GetPath()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_255">255</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_256">256</td><td nowrap="nowrap"> .. index::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_257">257</td><td nowrap="nowrap"> triple: module; search; path</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_258">258</td><td nowrap="nowrap"> single: path (in module sys)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_259">259</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__3">n</a></td><td class="diff_header" id="from12_260">260-</td><td nowrap="nowrap"> Return the default module search path; this is computed from the<span class="diff_sub"> </span> program name</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to12__3">n</a></td><td class="diff_header" id="to12_261">261+</td><td nowrap="nowrap"> Return the default module search path; this is computed from the program name</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_261">261-</td><td nowrap="nowrap"> (set by :cfunc:`Py_SetProgramName` above) and some environment variables.<span class="diff_sub"> The</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_262">262+</td><td nowrap="nowrap"> (set by :cfunc:`Py_SetProgramName` above) and some environment variables.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_262">262-</td><td nowrap="nowrap"> returned string consists of a series of directory names separated by a<span class="diff_sub"> platform</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_263">263+</td><td nowrap="nowrap"> <span class="diff_add"> The</span> returned string consists of a series of directory names separated by a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_263">263-</td><td nowrap="nowrap"> dependent delimiter character. The delimiter character is ``':'``<span class="diff_sub"> on Unix and</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_264">264+</td><td nowrap="nowrap"> <span class="diff_add"> platform</span> dependent delimiter character. The delimiter character is ``':'``</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_264">264-</td><td nowrap="nowrap"> Mac OS X, ``';'`` on Windows. The returned string points into<span class="diff_sub"> static storage;</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_265">265+</td><td nowrap="nowrap"> <span class="diff_add"> on Unix and</span> Mac OS X, ``';'`` on Windows. The returned string points into</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_265">265-</td><td nowrap="nowrap"><span class="diff_sub"> the caller should not modify its value. The value is available to Python code</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_266">266+</td><td nowrap="nowrap"><span class="diff_add"> static storage; the caller should not modify its value. The list</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_266">266-</td><td nowrap="nowrap"><span class="diff_sub"> as the list ``sys.path``, which may be modified to change the future search path</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_267">267+</td><td nowrap="nowrap"><span class="diff_add"> :data:`sys.path` is initialized with this value on interpreter startup; it</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_267">267-</td><td nowrap="nowrap"><span class="diff_sub"> for loaded modules.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_268">268+</td><td nowrap="nowrap"><span class="diff_add"> can be (and usually is) modified later to change the search path for loading</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_269">269+</td><td nowrap="nowrap"><span class="diff_add"> modules.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_268">268</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_269">269</td><td nowrap="nowrap"> .. XXX should give the exact rules</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_270">270</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_271">271</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_272">272</td><td nowrap="nowrap">.. cfunction:: const char* Py_GetVersion()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_273">273</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_274">274</td><td nowrap="nowrap"> Return the version of this Python interpreter. This is a string that looks</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_275">275</td><td nowrap="nowrap"> something like ::</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to12__3"></td><td class="diff_header" id="from12_277">277</td><td nowrap="nowrap"> "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_278">278</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_279">279</td><td nowrap="nowrap"> .. index:: single: version (in module sys)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_280">280</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_281">281</td><td nowrap="nowrap"> The first word (up to the first space character) is the current Python version;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_282">282</td><td nowrap="nowrap"> the first three characters are the major and minor version separated by a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_283">283</td><td nowrap="nowrap"> period. The returned string points into static storage; the caller should not</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_284">284</td><td nowrap="nowrap"> modify its value. The value is available to Python code as ``sys.version``.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__4">n</a></td><td class="diff_header" id="from12_285">285-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_286">286-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_287">287-</td><td nowrap="nowrap"><span class="diff_sub">.. cfunction:: const char* Py_GetBuildNumber()</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_288">288-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_289">289-</td><td nowrap="nowrap"><span class="diff_sub"> Return a string representing the Subversion revision that this Python executable</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_290">290-</td><td nowrap="nowrap"><span class="diff_sub"> was built from. This number is a string because it may contain a trailing 'M'</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_291">291-</td><td nowrap="nowrap"><span class="diff_sub"> if Python was built from a mixed revision source tree.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_292">292-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_293">293-</td><td nowrap="nowrap"><span class="diff_sub"> .. versionadded:: 2.5</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_294">294</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_295">295</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_296">296</td><td nowrap="nowrap">.. cfunction:: const char* Py_GetPlatform()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_297">297</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_298">298</td><td nowrap="nowrap"> .. index:: single: platform (in module sys)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_299">299</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_300">300</td><td nowrap="nowrap"> Return the platform identifier for the current platform. On Unix, this is</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_301">301</td><td nowrap="nowrap"> formed from the "official" name of the operating system, converted to lower</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to12__4"></td><td class="diff_header" id="from12_341">341</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_342">342</td><td nowrap="nowrap"> .. index:: single: version (in module sys)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_343">343</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_344">344</td><td nowrap="nowrap"> The returned string points into static storage; the caller should not modify its</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_345">345</td><td nowrap="nowrap"> value. The value is available to Python code as part of the variable</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_346">346</td><td nowrap="nowrap"> ``sys.version``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_347">347</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_348">348</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__5">n</a></td><td class="diff_header" id="from12_349">349-</td><td nowrap="nowrap">.. cfunction:: void PySys_SetArgv(int argc, char **argv)</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to12__5">n</a></td><td class="diff_header" id="to12_342">342+</td><td nowrap="nowrap">.. cfunction:: void PySys_SetArgv<span class="diff_add">Ex</span>(int argc, char **argv<span class="diff_add">, int updatepath</span>)</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_350">350</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_351">351</td><td nowrap="nowrap"> .. index::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_352">352</td><td nowrap="nowrap"> single: main()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_353">353</td><td nowrap="nowrap"> single: Py_FatalError()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_354">354</td><td nowrap="nowrap"> single: argv (in module sys)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_355">355</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to12__5"></td><td class="diff_header" id="from12_356">356</td><td nowrap="nowrap"> Set :data:`sys.argv` based on *argc* and *argv*. These parameters are</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_357">357</td><td nowrap="nowrap"> similar to those passed to the program's :cfunc:`main` function with the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_358">358</td><td nowrap="nowrap"> difference that the first entry should refer to the script file to be</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_359">359</td><td nowrap="nowrap"> executed rather than the executable hosting the Python interpreter. If there</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_360">360</td><td nowrap="nowrap"> isn't a script that will be run, the first entry in *argv* can be an empty</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_361">361</td><td nowrap="nowrap"> string. If this function fails to initialize :data:`sys.argv`, a fatal</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_362">362</td><td nowrap="nowrap"> condition is signalled using :cfunc:`Py_FatalError`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_363">363</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__6">n</a></td><td class="diff_header" id="from12_364">364-</td><td nowrap="nowrap"><span class="diff_sub"> This function also prepends the executed script's path to :data:`sys.path`.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to12__6">n</a></td><td class="diff_header" id="to12_357">357+</td><td nowrap="nowrap"><span class="diff_add"> If *updatepath* is zero, this is all the function does. If *updatepath*</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_365">365-</td><td nowrap="nowrap"><span class="diff_sub"> If no script is executed (in the case of calling ``python -c`` or just the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_358">358+</td><td nowrap="nowrap"><span class="diff_add"> is non-zero, the function also modifies :data:`sys.path` according to the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_366">366-</td><td nowrap="nowrap"><span class="diff_sub"> interactive interpreter), the empty string is used instead.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_359">359+</td><td nowrap="nowrap"><span class="diff_add"> following algorithm:</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_360">360+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_361">361+</td><td nowrap="nowrap"><span class="diff_add"> - If the name of an existing script is passed in ``argv[0]``, the absolute</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_362">362+</td><td nowrap="nowrap"><span class="diff_add"> path of the directory where the script is located is prepended to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_363">363+</td><td nowrap="nowrap"><span class="diff_add"> :data:`sys.path`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_364">364+</td><td nowrap="nowrap"><span class="diff_add"> - Otherwise (that is, if *argc* is 0 or ``argv[0]`` doesn't point</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_365">365+</td><td nowrap="nowrap"><span class="diff_add"> to an existing file name), an empty string is prepended to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_366">366+</td><td nowrap="nowrap"><span class="diff_add"> :data:`sys.path`, which is the same as prepending the current working</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_367">367+</td><td nowrap="nowrap"><span class="diff_add"> directory (``"."``).</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_368">368+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_369">369+</td><td nowrap="nowrap"><span class="diff_add"> .. note::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_370">370+</td><td nowrap="nowrap"><span class="diff_add"> It is recommended that applications embedding the Python interpreter</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_371">371+</td><td nowrap="nowrap"><span class="diff_add"> for purposes other than executing a single script pass 0 as *updatepath*,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_372">372+</td><td nowrap="nowrap"><span class="diff_add"> and update :data:`sys.path` themselves if desired.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_373">373+</td><td nowrap="nowrap"><span class="diff_add"> See `CVE-2008-5983 <http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2008-5983>`_.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_374">374+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_375">375+</td><td nowrap="nowrap"><span class="diff_add"> On versions before 2.6.6, you can achieve the same effect by manually</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_376">376+</td><td nowrap="nowrap"><span class="diff_add"> popping the first :data:`sys.path` element after having called</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to12__6"></td><td class="diff_header" id="to12_377">377+</td><td nowrap="nowrap"><span class="diff_add"> :cfunc:`PySys_SetArgv`, for example using::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_378">378+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_379">379+</td><td nowrap="nowrap"><span class="diff_add"> PyRun_SimpleString("import sys; sys.path.pop(0)\n");</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_380">380+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_381">381+</td><td nowrap="nowrap"><span class="diff_add"> .. versionadded:: 2.6.6</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_367">367</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_368">368</td><td nowrap="nowrap"> .. XXX impl. doesn't seem consistent in allowing 0/NULL for the params;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_369">369</td><td nowrap="nowrap"> check w/ Guido.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__7">n</a></td><td class="diff_header" id="to12_385">385+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_386">386+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_387">387+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: void PySys_SetArgv(int argc, char **argv)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_388">388+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to12__7"></td><td class="diff_header" id="to12_389">389+</td><td nowrap="nowrap"><span class="diff_add"> This function works like :cfunc:`PySys_SetArgv` with *updatepath* set to 1.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_370">370</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_371">371</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_372">372</td><td nowrap="nowrap">.. cfunction:: void Py_SetPythonHome(char *home)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_373">373</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_374">374</td><td nowrap="nowrap"> Set the default "home" directory, that is, the location of the standard</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_375">375</td><td nowrap="nowrap"> Python libraries. The libraries are searched in</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_376">376</td><td nowrap="nowrap"> :file:`{home}/lib/python{version}` and :file:`{home}/lib/python{version}`.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__8">n</a></td><td class="diff_header" id="to12_397">397+</td><td nowrap="nowrap"><span class="diff_add"> The argument should point to a zero-terminated character string in static</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_398">398+</td><td nowrap="nowrap"><span class="diff_add"> storage whose contents will not change for the duration of the program's</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_399">399+</td><td nowrap="nowrap"><span class="diff_add"> execution. No code in the Python interpreter will change the contents of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_400">400+</td><td nowrap="nowrap"><span class="diff_add"> this storage.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_377">377</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_378">378</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_379">379</td><td nowrap="nowrap">.. cfunction:: char* Py_GetPythonHome()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_380">380</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_381">381</td><td nowrap="nowrap"> Return the default "home", that is, the value set by a previous call to</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_382">382</td><td nowrap="nowrap"> :cfunc:`Py_SetPythonHome`, or the value of the :envvar:`PYTHONHOME`</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_383">383</td><td nowrap="nowrap"> environment variable if it is set.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_384">384</td><td nowrap="nowrap"></td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to12__8"></td><td class="diff_header" id="from12_414">414</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_415">415</td><td nowrap="nowrap">.. index::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_416">416</td><td nowrap="nowrap"> single: PyThreadState</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_417">417</td><td nowrap="nowrap"> single: PyThreadState</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_418">418</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_419">419</td><td nowrap="nowrap">The Python interpreter needs to keep some bookkeeping information separate per</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_420">420</td><td nowrap="nowrap">thread --- for this it uses a data structure called :ctype:`PyThreadState`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_421">421</td><td nowrap="nowrap">There's one global variable, however: the pointer to the current</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__9">n</a></td><td class="diff_header" id="from12_422">422-</td><td nowrap="nowrap"><span class="diff_sub">:ctype:`PyThreadState` structure. While most thread packages have a way to</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to12__9">n</a></td><td class="diff_header" id="to12_446">446+</td><td nowrap="nowrap"><span class="diff_add">:ctype:`PyThreadState` structure. Before the addition of :dfn:`thread-local</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_423">423-</td><td nowrap="nowrap"><span class="diff_sub">store "per-thread global data," Python's internal platform independent thread</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_447">447+</td><td nowrap="nowrap"><span class="diff_add">storage` (:dfn:`TLS`) the current thread state had to be manipulated</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_424">424-</td><td nowrap="nowrap"><span class="diff_sub">abstraction doesn't support this yet. Therefore, the current thread state must</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_448">448+</td><td nowrap="nowrap"><span class="diff_add">explicitly.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_425">425-</td><td nowrap="nowrap"><span class="diff_sub">be manipulated explicitly.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_426">426</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_427">427</td><td nowrap="nowrap">This is easy enough in most cases. Most code manipulating the global</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_428">428</td><td nowrap="nowrap">interpreter lock has the following simple structure::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_429">429</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_430">430</td><td nowrap="nowrap"> Save the thread state in a local variable.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_431">431</td><td nowrap="nowrap"> Release the global interpreter lock.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_432">432</td><td nowrap="nowrap"> ...Do some blocking I/O operation...</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_433">433</td><td nowrap="nowrap"> Reacquire the global interpreter lock.</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to12__9"></td><td class="diff_header" id="from12_487">487</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_488">488</td><td nowrap="nowrap">The global interpreter lock is used to protect the pointer to the current thread</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_489">489</td><td nowrap="nowrap">state. When releasing the lock and saving the thread state, the current thread</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_490">490</td><td nowrap="nowrap">state pointer must be retrieved before the lock is released (since another</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_491">491</td><td nowrap="nowrap">thread could immediately acquire the lock and store its own thread state in the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_492">492</td><td nowrap="nowrap">global variable). Conversely, when acquiring the lock and restoring the thread</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_493">493</td><td nowrap="nowrap">state, the lock must be acquired before storing the thread state pointer.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_494">494</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__10">n</a></td><td class="diff_header" id="from12_495">495-</td><td nowrap="nowrap"><span class="diff_sub">Why am I going on with so much detail about this? Because when threads are</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to12__10">n</a></td><td class="diff_header" id="to12_518">518+</td><td nowrap="nowrap"><span class="diff_add">It is important to note that when threads are created from C, they don't have</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_496">496-</td><td nowrap="nowrap"><span class="diff_sub">created from C, they don't have the global interpreter lock, nor is there a</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_519">519+</td><td nowrap="nowrap"><span class="diff_add">the global interpreter lock, nor is there a thread state data structure for</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_497">497-</td><td nowrap="nowrap"><span class="diff_sub">thread state data structure for them. Such threads must bootstrap themselves</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_520">520+</td><td nowrap="nowrap"><span class="diff_add">them. Such threads must bootstrap themselves into existence, by first</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_498">498-</td><td nowrap="nowrap"><span class="diff_sub">into existence, by first creating a thread state data structure, then acquiring</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_521">521+</td><td nowrap="nowrap"><span class="diff_add">creating a thread state data structure, then acquiring the lock, and finally</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_499">499-</td><td nowrap="nowrap"><span class="diff_sub">the lock, and finally storing their thread state pointer, before they can start</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_522">522+</td><td nowrap="nowrap"><span class="diff_add">storing their thread state pointer, before they can start using the Python/C</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_500">500-</td><td nowrap="nowrap"><span class="diff_sub">using the Python/C </span>API. When they are done, they should reset the thread state</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_523">523+</td><td nowrap="nowrap">API. When they are done, they should reset the thread state<span class="diff_add"> pointer, release</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from12_501">501-</td><td nowrap="nowrap"><span class="diff_sub">pointer, release </span>the lock, and finally free their thread state data structure.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_524">524+</td><td nowrap="nowrap">the lock, and finally free their thread state data structure.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_502">502</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_503">503</td><td nowrap="nowrap">Beginning with version 2.3, threads can now take advantage of the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_504">504</td><td nowrap="nowrap">:cfunc:`PyGILState_\*` functions to do all of the above automatically. The</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_505">505</td><td nowrap="nowrap">typical idiom for calling into Python from a C thread is now::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_506">506</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_507">507</td><td nowrap="nowrap"> PyGILState_STATE gstate;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_508">508</td><td nowrap="nowrap"> gstate = PyGILState_Ensure();</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_509">509</td><td nowrap="nowrap"></td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to12__10"></td><td class="diff_header" id="from12_515">515</td><td nowrap="nowrap"> PyGILState_Release(gstate);</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_516">516</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_517">517</td><td nowrap="nowrap">Note that the :cfunc:`PyGILState_\*` functions assume there is only one global</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_518">518</td><td nowrap="nowrap">interpreter (created automatically by :cfunc:`Py_Initialize`). Python still</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_519">519</td><td nowrap="nowrap">supports the creation of additional interpreters (using</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_520">520</td><td nowrap="nowrap">:cfunc:`Py_NewInterpreter`), but mixing multiple interpreters and the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_521">521</td><td nowrap="nowrap">:cfunc:`PyGILState_\*` API is unsupported.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_522">522</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to12__top">t</a></td><td class="diff_header" id="to12_546">546+</td><td nowrap="nowrap"><span class="diff_add">Another important thing to note about threads is their behaviour in the face</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_547">547+</td><td nowrap="nowrap"><span class="diff_add">of the C :cfunc:`fork` call. On most systems with :cfunc:`fork`, after a</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_548">548+</td><td nowrap="nowrap"><span class="diff_add">process forks only the thread that issued the fork will exist. That also</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_549">549+</td><td nowrap="nowrap"><span class="diff_add">means any locks held by other threads will never be released. Python solves</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_550">550+</td><td nowrap="nowrap"><span class="diff_add">this for :func:`os.fork` by acquiring the locks it uses internally before</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_551">551+</td><td nowrap="nowrap"><span class="diff_add">the fork, and releasing them afterwards. In addition, it resets any</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_552">552+</td><td nowrap="nowrap"><span class="diff_add">:ref:`lock-objects` in the child. When extending or embedding Python, there</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_553">553+</td><td nowrap="nowrap"><span class="diff_add">is no way to inform Python of additional (non-Python) locks that need to be</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_554">554+</td><td nowrap="nowrap"><span class="diff_add">acquired before or reset after a fork. OS facilities such as</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_555">555+</td><td nowrap="nowrap"><span class="diff_add">:cfunc:`posix_atfork` would need to be used to accomplish the same thing.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_556">556+</td><td nowrap="nowrap"><span class="diff_add">Additionally, when extending or embedding Python, calling :cfunc:`fork`</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_557">557+</td><td nowrap="nowrap"><span class="diff_add">directly rather than through :func:`os.fork` (and returning to or calling</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_558">558+</td><td nowrap="nowrap"><span class="diff_add">into Python) may result in a deadlock by one of Python's internal locks</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_559">559+</td><td nowrap="nowrap"><span class="diff_add">being held by a thread that is defunct after the fork.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_560">560+</td><td nowrap="nowrap"><span class="diff_add">:cfunc:`PyOS_AfterFork` tries to reset the necessary locks, but is not</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to12_561">561+</td><td nowrap="nowrap"><span class="diff_add">always able to.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from12_523">523</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_524">524</td><td nowrap="nowrap">.. ctype:: PyInterpreterState</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_525">525</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_526">526</td><td nowrap="nowrap"> This data structure represents the state shared by a number of cooperating</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_527">527</td><td nowrap="nowrap"> threads. Threads belonging to the same interpreter share their module</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_528">528</td><td nowrap="nowrap"> administration and a few other internal items. There are no public members in</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_529">529</td><td nowrap="nowrap"> this structure.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from12_530">530</td><td nowrap="nowrap"></td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/int.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,56 @@ +--- r262/c-api/int.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/int.rst 2009-10-27 23:34:21.573917000 +0900 +@@ -59,24 +59,33 @@ + + Create a new integer object with a value of *ival*. + + The current implementation keeps an array of integer objects for all integers + between ``-5`` and ``256``, when you create an int in that range you actually + just get back a reference to the existing object. So it should be possible to + change the value of ``1``. I suspect the behaviour of Python in this case is + undefined. :-) + + + .. cfunction:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival) + ++ Create a new integer object with a value of *ival*. If the value is larger ++ than ``LONG_MAX`` or smaller than ``LONG_MIN``, a long integer object is ++ returned. ++ ++ .. versionadded:: 2.5 ++ ++ ++.. cfunction:: PyObject* PyInt_FromSize_t(size_t ival) ++ + Create a new integer object with a value of *ival*. If the value exceeds + ``LONG_MAX``, a long integer object is returned. + + .. versionadded:: 2.5 + + + .. cfunction:: long PyInt_AsLong(PyObject *io) + + Will first attempt to cast the object to a :ctype:`PyIntObject`, if it is not + already one, and then return its value. If there is an error, ``-1`` is + returned, and the caller should check ``PyErr_Occurred()`` to find out whether + there was an error, or whether the value just happened to be -1. +@@ -113,18 +122,18 @@ + + .. versionadded:: 2.5 + + + .. cfunction:: long PyInt_GetMax() + + .. index:: single: LONG_MAX + + Return the system's idea of the largest integer it can handle + (:const:`LONG_MAX`, as defined in the system header files). + + +-.. cfunction:: int PyInt_ClearFreeList(void) ++.. cfunction:: int PyInt_ClearFreeList() + + Clear the integer free list. Return the number of items that could not + be freed. + + .. versionadded:: 2.6 ======================================= --- /dev/null +++ /c-api/diff/int.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,61 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to13__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/int.rst => r266/c-api/int.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to13__0"></td><td class="diff_header" id="from13_63">63</td><td nowrap="nowrap"> between ``-5`` and ``256``, when you create an int in that range you actually</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_64">64</td><td nowrap="nowrap"> just get back a reference to the existing object. So it should be possible to</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_65">65</td><td nowrap="nowrap"> change the value of ``1``. I suspect the behaviour of Python in this case is</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_66">66</td><td nowrap="nowrap"> undefined. :-)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_67">67</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_68">68</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_69">69</td><td nowrap="nowrap">.. cfunction:: PyObject* PyInt_FromSsize_t(Py_ssize_t ival)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_70">70</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to13__1">n</a></td><td class="diff_header" id="to13_71">71+</td><td nowrap="nowrap"><span class="diff_add"> Create a new integer object with a value of *ival*. If the value is larger</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to13_72">72+</td><td nowrap="nowrap"><span class="diff_add"> than ``LONG_MAX`` or smaller than ``LONG_MIN``, a long integer object is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to13_73">73+</td><td nowrap="nowrap"><span class="diff_add"> returned.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to13_74">74+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to13_75">75+</td><td nowrap="nowrap"><span class="diff_add"> .. versionadded:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to13_76">76+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to13_77">77+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to13_78">78+</td><td nowrap="nowrap"><span class="diff_add">.. cfunction:: PyObject* PyInt_FromSize_t(size_t ival)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to13_79">79+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from13_71">71</td><td nowrap="nowrap"> Create a new integer object with a value of *ival*. If the value exceeds</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_72">72</td><td nowrap="nowrap"> ``LONG_MAX``, a long integer object is returned.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_73">73</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_74">74</td><td nowrap="nowrap"> .. versionadded:: 2.5</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_75">75</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_76">76</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_77">77</td><td nowrap="nowrap">.. cfunction:: long PyInt_AsLong(PyObject *io)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_78">78</td><td nowrap="nowrap"></td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to13__1"></td><td class="diff_header" id="from13_117">117</td><td nowrap="nowrap">.. cfunction:: long PyInt_GetMax()</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_118">118</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_119">119</td><td nowrap="nowrap"> .. index:: single: LONG_MAX</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_120">120</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_121">121</td><td nowrap="nowrap"> Return the system's idea of the largest integer it can handle</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_122">122</td><td nowrap="nowrap"> (:const:`LONG_MAX`, as defined in the system header files).</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_123">123</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_124">124</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to13__top">t</a></td><td class="diff_header" id="from13_125">125-</td><td nowrap="nowrap">.. cfunction:: int PyInt_ClearFreeList(<span class="diff_sub">void</span>)</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to13__top">t</a></td><td class="diff_header" id="to13_134">134+</td><td nowrap="nowrap">.. cfunction:: int PyInt_ClearFreeList()</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from13_126">126</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_127">127</td><td nowrap="nowrap"> Clear the integer free list. Return the number of items that could not</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_128">128</td><td nowrap="nowrap"> be freed.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_129">129</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from13_130">130</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/intro.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,29 @@ +--- r262/c-api/intro.rst 2009-02-23 19:41:11.107573000 +0900 ++++ r266/c-api/intro.rst 2009-04-29 03:23:28.138007000 +0900 +@@ -35,25 +35,25 @@ + Include Files + ============= + + All function, type and macro definitions needed to use the Python/C API are + included in your code by the following line:: + + #include "Python.h" + + This implies inclusion of the following standard headers: ``<stdio.h>``, + ``<string.h>``, ``<errno.h>``, ``<limits.h>``, and ``<stdlib.h>`` (if + available). + +-.. warning:: ++.. note:: + + Since Python may define some pre-processor definitions which affect the standard + headers on some systems, you *must* include :file:`Python.h` before any standard + headers are included. + + All user visible names defined by Python.h (except those defined by the included + standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning + with ``_Py`` are for internal use by the Python implementation and should not be + used by extension writers. Structure member names do not have a reserved prefix. + + **Important:** user code should never define names that begin with ``Py`` or + ``_Py``. This confuses the reader, and jeopardizes the portability of the user ======================================= --- /dev/null +++ /c-api/diff/intro.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,50 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to14__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/intro.rst => r266/c-api/intro.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to14__0"></td><td class="diff_header" id="from14_39">39</td><td nowrap="nowrap">included in your code by the following line::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_40">40</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_41">41</td><td nowrap="nowrap"> #include "Python.h"</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_42">42</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_43">43</td><td nowrap="nowrap">This implies inclusion of the following standard headers: ``<stdio.h>``,</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_44">44</td><td nowrap="nowrap">``<string.h>``, ``<errno.h>``, ``<limits.h>``, and ``<stdlib.h>`` (if</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_45">45</td><td nowrap="nowrap">available).</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_46">46</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to14__top">t</a></td><td class="diff_header" id="from14_47">47-</td><td nowrap="nowrap"><span class="diff_sub">.. warning::</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to14__top">t</a></td><td class="diff_header" id="to14_47">47+</td><td nowrap="nowrap"><span class="diff_add">.. note::</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from14_48">48</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_49">49</td><td nowrap="nowrap"> Since Python may define some pre-processor definitions which affect the standard</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_50">50</td><td nowrap="nowrap"> headers on some systems, you *must* include :file:`Python.h` before any standard</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_51">51</td><td nowrap="nowrap"> headers are included.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_52">52</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_53">53</td><td nowrap="nowrap">All user visible names defined by Python.h (except those defined by the included</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_54">54</td><td nowrap="nowrap">standard headers) have one of the prefixes ``Py`` or ``_Py``. Names beginning</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from14_55">55</td><td nowrap="nowrap">with ``_Py`` are for internal use by the Python implementation and should not be</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/list.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,221 @@ +--- r262/c-api/list.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/list.rst 2010-05-14 06:16:53.370897000 +0900 +@@ -6,140 +6,182 @@ + ------------ + + .. index:: object: list + + + .. ctype:: PyListObject + + This subtype of :ctype:`PyObject` represents a Python list object. + + + .. cvar:: PyTypeObject PyList_Type + +- .. 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`` in the Python layer. + + + .. cfunction:: int PyList_Check(PyObject *p) + + Return true if *p* is a list object or an instance of a subtype of the list + type. + + .. versionchanged:: 2.2 + Allowed subtypes to be accepted. + + + .. 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 + + + .. cfunction:: PyObject* PyList_New(Py_ssize_t len) + + Return a new list of length *len* on success, or *NULL* on failure. + + .. 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) + + .. index:: builtin: len + + 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]``. ++ and *high*. Return *NULL* and set an exception if unsuccessful. Analogous ++ to ``list[low:high]``. Negative indices, as when slicing from Python, are not ++ supported. ++ ++ .. 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. Negative indices, as when ++ slicing from Python, are not supported. ++ ++ .. 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) + + Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on + failure. This is the equivalent of ``list.reverse()``. + + + .. cfunction:: PyObject* PyList_AsTuple(PyObject *list) + + .. index:: builtin: tuple + ======================================= --- /dev/null +++ /c-api/diff/list.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,162 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to15__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/list.rst => r266/c-api/list.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to15__0"></td><td class="diff_header" id="from15_10">10</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_11">11</td><td nowrap="nowrap">.. ctype:: PyListObject</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_12">12</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_13">13</td><td nowrap="nowrap"> This subtype of :ctype:`PyObject` represents a Python list object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_14">14</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_15">15</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_16">16</td><td nowrap="nowrap">.. cvar:: PyTypeObject PyList_Type</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_17">17</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__1">n</a></td><td class="diff_header" id="from15_18">18-</td><td nowrap="nowrap"><span class="diff_sub"> .. index:: single: ListType (in module types)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_19">19-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_20">20-</td><td nowrap="nowrap"> This instance of :ctype:`PyTypeObject` represents the Python list type. This<span class="diff_sub"> is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_18">18+</td><td nowrap="nowrap"> This instance of :ctype:`PyTypeObject` represents the Python list type. This</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_21">21-</td><td nowrap="nowrap"> the same object as ``list`` <span class="diff_sub">and ``types.ListType`` </span>in the Python layer.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_19">19+</td><td nowrap="nowrap"> <span class="diff_add"> is</span> the same object as ``list`` in the Python layer.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_22">22</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_23">23</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_24">24</td><td nowrap="nowrap">.. cfunction:: int PyList_Check(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_25">25</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_26">26</td><td nowrap="nowrap"> Return true if *p* is a list object or an instance of a subtype of the list</td></tr> <tr><td class="diff_next" id="difflib_chg_to15__1"></td><td class="diff_header" id="from15_27">27</td><td nowrap="nowrap"> type.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_28">28</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_29">29</td><td nowrap="nowrap"> .. versionchanged:: 2.2</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_30">30</td><td nowrap="nowrap"> Allowed subtypes to be accepted.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_31">31</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_32">32</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_33">33</td><td nowrap="nowrap">.. cfunction:: int PyList_CheckExact(PyObject *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_34">34</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__2">n</a></td><td class="diff_header" id="from15_35">35-</td><td nowrap="nowrap"> Return true if *p* is a list object, but not an instance of a subtype of<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__2">n</a></td><td class="diff_header" id="to15_33">33+</td><td nowrap="nowrap"> Return true if *p* is a list object, but not an instance of a subtype of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_36">36-</td><td nowrap="nowrap"> list type.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_34">34+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> list type.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_37">37</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_38">38</td><td nowrap="nowrap"> .. versionadded:: 2.2</td></tr> <tr><td class="diff_next" id="difflib_chg_to15__2"></td><td class="diff_header" id="from15_39">39</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_40">40</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_41">41</td><td nowrap="nowrap">.. cfunction:: PyObject* PyList_New(Py_ssize_t len)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_42">42</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_43">43</td><td nowrap="nowrap"> Return a new list of length *len* on success, or *NULL* on failure.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_44">44</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_45">45</td><td nowrap="nowrap"> .. note::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_46">46</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__3">n</a></td><td class="diff_header" id="from15_47">47-</td><td nowrap="nowrap"> If *length* is greater than zero, the returned list object's items are<span class="diff_sub"> set to</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__3">n</a></td><td class="diff_header" id="to15_45">45+</td><td nowrap="nowrap"> If *length* is greater than zero, the returned list object's items are</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_48">48-</td><td nowrap="nowrap"> ``NULL``. Thus you cannot use abstract API functions such as</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_46">46+</td><td nowrap="nowrap"> <span class="diff_add"> set to</span> ``NULL``. Thus you cannot use abstract API functions such as</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_49">49-</td><td nowrap="nowrap"> :cfunc:`PySequence_SetItem` or expose the object to Python code before<span class="diff_sub"> setting</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_47">47+</td><td nowrap="nowrap"> :cfunc:`PySequence_SetItem` or expose the object to Python code before</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_50">50-</td><td nowrap="nowrap"> all items to a real object with :cfunc:`PyList_SetItem`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_48">48+</td><td nowrap="nowrap"> <span class="diff_add"> setting</span> all items to a real object with :cfunc:`PyList_SetItem`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_49">49+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_50">50+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_51">51+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` for *size*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_52">52+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_51">51</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to15__3"></td><td class="diff_header" id="from15_52">52</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_53">53</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PyList_Size(PyObject *list)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_54">54</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_55">55</td><td nowrap="nowrap"> .. index:: builtin: len</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_56">56</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_57">57</td><td nowrap="nowrap"> Return the length of the list object in *list*; this is equivalent to</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_58">58</td><td nowrap="nowrap"> ``len(list)`` on a list object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_59">59</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__4">n</a></td><td class="diff_header" id="to15_62">62+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to15__4"></td><td class="diff_header" id="to15_63">63+</td><td nowrap="nowrap"><span class="diff_add"> This function returned an :ctype:`int`. This might require changes in</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_64">64+</td><td nowrap="nowrap"><span class="diff_add"> your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_65">65+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_60">60</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_61">61</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PyList_GET_SIZE(PyObject *list)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_62">62</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_63">63</td><td nowrap="nowrap"> Macro form of :cfunc:`PyList_Size` without error checking.</td></tr> <tr><td class="diff_next" id="difflib_chg_to15__5"></td><td class="diff_header" id="from15_64">64</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__5">n</a></td><td class="diff_header" id="to15_71">71+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_72">72+</td><td nowrap="nowrap"><span class="diff_add"> This macro returned an :ctype:`int`. This might require changes in your</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_73">73+</td><td nowrap="nowrap"><span class="diff_add"> code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_74">74+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_65">65</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_66">66</td><td nowrap="nowrap">.. cfunction:: PyObject* PyList_GetItem(PyObject *list, Py_ssize_t index)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_67">67</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__6">n</a></td><td class="diff_header" id="from15_68">68-</td><td nowrap="nowrap"> Return the object at position *pos* in the list pointed to by *p*. The<span class="diff_sub"> position</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__6">n</a></td><td class="diff_header" id="to15_78">78+</td><td nowrap="nowrap"> Return the object at position *pos* in the list pointed to by *p*. The</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_69">69-</td><td nowrap="nowrap"> must be positive, indexing from the end of the list is not<span class="diff_sub"> supported. If *pos*</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_79">79+</td><td nowrap="nowrap"> <span class="diff_add"> position</span> must be positive, indexing from the end of the list is not</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_70">70-</td><td nowrap="nowrap"><span class="diff_sub"> is out of bounds, return *NULL* and set an :exc:`IndexError` exception.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_80">80+</td><td nowrap="nowrap"><span class="diff_add"> supported. If *pos* is out of bounds, return *NULL* and set an</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_81">81+</td><td nowrap="nowrap"><span class="diff_add"> :exc:`IndexError` exception.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_82">82+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_83">83+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to15__6"></td><td class="diff_header" id="to15_84">84+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` for *index*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_85">85+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_71">71</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_72">72</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_73">73</td><td nowrap="nowrap">.. cfunction:: PyObject* PyList_GET_ITEM(PyObject *list, Py_ssize_t i)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_74">74</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_75">75</td><td nowrap="nowrap"> Macro form of :cfunc:`PyList_GetItem` without error checking.</td></tr> <tr><td class="diff_next" id="difflib_chg_to15__7"></td><td class="diff_header" id="from15_76">76</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__7">n</a></td><td class="diff_header" id="to15_92">92+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_93">93+</td><td nowrap="nowrap"><span class="diff_add"> This macro used an :ctype:`int` for *i*. This might require changes in</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_94">94+</td><td nowrap="nowrap"><span class="diff_add"> your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_95">95+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to15__8"></td><td class="diff_header" id="from15_77">77</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_78">78</td><td nowrap="nowrap">.. cfunction:: int PyList_SetItem(PyObject *list, Py_ssize_t index, PyObject *item)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_79">79</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__8">n</a></td><td class="diff_header" id="from15_80">80-</td><td nowrap="nowrap"> Set the item at index *index* in list to *item*. Return ``0`` on success<span class="diff_sub"> or</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__8">n</a></td><td class="diff_header" id="to15_99">99+</td><td nowrap="nowrap"> Set the item at index *index* in list to *item*. Return ``0`` on success</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_81">81-</td><td nowrap="nowrap"> ``-1`` on failure.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_100">100+</td><td nowrap="nowrap"> <span class="diff_add"> or</span> ``-1`` on failure.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_82">82</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_83">83</td><td nowrap="nowrap"> .. note::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_84">84</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__9">n</a></td><td class="diff_header" id="from15_85">85-</td><td nowrap="nowrap"> This function "steals" a reference to *item* and discards a reference to<span class="diff_sub"> an item</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__9">n</a></td><td class="diff_header" id="to15_104">104+</td><td nowrap="nowrap"> This function "steals" a reference to *item* and discards a reference to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_86">86-</td><td nowrap="nowrap"> already in the list at the affected position.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_105">105+</td><td nowrap="nowrap"> <span class="diff_add"> an item</span> already in the list at the affected position.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to15__9"></td><td class="diff_header" id="to15_106">106+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_107">107+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_108">108+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` for *index*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_109">109+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_87">87</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to15__10"></td><td class="diff_header" id="from15_88">88</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_89">89</td><td nowrap="nowrap">.. cfunction:: void PyList_SET_ITEM(PyObject *list, Py_ssize_t i, PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_90">90</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__10">n</a></td><td class="diff_header" id="from15_91">91-</td><td nowrap="nowrap"> Macro form of :cfunc:`PyList_SetItem` without error checking. This is<span class="diff_sub"> normally</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__10">n</a></td><td class="diff_header" id="to15_114">114+</td><td nowrap="nowrap"> Macro form of :cfunc:`PyList_SetItem` without error checking. This is</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_92">92-</td><td nowrap="nowrap"> only used to fill in new lists where there is no previous content.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_115">115+</td><td nowrap="nowrap"> <span class="diff_add"> normally</span> only used to fill in new lists where there is no previous content.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_93">93</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_94">94</td><td nowrap="nowrap"> .. note::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_95">95</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__11">n</a></td><td class="diff_header" id="from15_96">96-</td><td nowrap="nowrap"> This <span class="diff_chg">fun</span>c<span class="diff_chg">ti</span>o<span class="diff_sub">n</span> "steals" a reference to *item*, and, unlike</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__11">n</a></td><td class="diff_header" id="to15_119">119+</td><td nowrap="nowrap"> This <span class="diff_chg">ma</span>c<span class="diff_chg">r</span>o "steals" a reference to *item*, and, unlike</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_97">97-</td><td nowrap="nowrap"> :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that<span class="diff_sub"> it</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_120">120+</td><td nowrap="nowrap"> :cfunc:`PyList_SetItem`, does *not* discard a reference to any item that</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_98">98-</td><td nowrap="nowrap"> being replaced; any reference in *list* at position *i* will be<span class="diff_sub"> leaked.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_121">121+</td><td nowrap="nowrap"> <span class="diff_add"> it</span> being replaced; any reference in *list* at position *i* will be</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_122">122+</td><td nowrap="nowrap"><span class="diff_add"> leaked.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to15__11"></td><td class="diff_header" id="to15_123">123+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_124">124+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_125">125+</td><td nowrap="nowrap"><span class="diff_add"> This macro used an :ctype:`int` for *i*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_126">126+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_99">99</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_100">100</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_101">101</td><td nowrap="nowrap">.. cfunction:: int PyList_Insert(PyObject *list, Py_ssize_t index, PyObject *item)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_102">102</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__12">n</a></td><td class="diff_header" id="from15_103">103-</td><td nowrap="nowrap"> Insert the item *item* into list *list* in front of index *index*. Return<span class="diff_sub"> ``0``</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__12">n</a></td><td class="diff_header" id="to15_131">131+</td><td nowrap="nowrap"> Insert the item *item* into list *list* in front of index *index*. Return</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_104">104-</td><td nowrap="nowrap"> if successful; return ``-1`` and set an exception if unsuccessful.<span class="diff_sub"> Analogous to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_132">132+</td><td nowrap="nowrap"> <span class="diff_add"> ``0``</span> if successful; return ``-1`` and set an exception if unsuccessful.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_105">105-</td><td nowrap="nowrap"> ``list.insert(index, item)``.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_133">133+</td><td nowrap="nowrap"> <span class="diff_add"> Analogous to</span> ``list.insert(index, item)``.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to15__12"></td><td class="diff_header" id="to15_134">134+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_135">135+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_136">136+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` for *index*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_137">137+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_106">106</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_107">107</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_108">108</td><td nowrap="nowrap">.. cfunction:: int PyList_Append(PyObject *list, PyObject *item)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_109">109</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next" id="difflib_chg_to15__13"><a href="#difflib_chg_to15__13">n</a></td><td class="diff_header" id="from15_110">110-</td><td nowrap="nowrap"> Append the object *item* at the end of list *list*. Return ``0`` if<span class="diff_sub"> successful;</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to15__13"><a href="#difflib_chg_to15__13">n</a></td><td class="diff_header" id="to15_142">142+</td><td nowrap="nowrap"> Append the object *item* at the end of list *list*. Return ``0`` if</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_111">111-</td><td nowrap="nowrap"> return ``-1`` and set an exception if unsuccessful. Analogous<span class="diff_sub"> to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_143">143+</td><td nowrap="nowrap"> <span class="diff_add"> successful;</span> return ``-1`` and set an exception if unsuccessful. Analogous</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_112">112-</td><td nowrap="nowrap"> ``list.append(item)``.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_144">144+</td><td nowrap="nowrap"> <span class="diff_add"> to</span> ``list.append(item)``.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_113">113</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_114">114</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_115">115</td><td nowrap="nowrap">.. cfunction:: PyObject* PyList_GetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_116">116</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_117">117</td><td nowrap="nowrap"> Return a list of the objects in *list* containing the objects *between* *low*</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__14">n</a></td><td class="diff_header" id="from15_118">118-</td><td nowrap="nowrap"> and *high*. Return *NULL* and set an exception if unsuccessful. Analogous<span class="diff_sub"> to</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__14">n</a></td><td class="diff_header" id="to15_150">150+</td><td nowrap="nowrap"> and *high*. Return *NULL* and set an exception if unsuccessful. <span class="diff_add"> </span>Analogous</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_119">119-</td><td nowrap="nowrap"><span class="diff_sub"> ``list[low:high]``.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_151">151+</td><td nowrap="nowrap"><span class="diff_add"> to ``list[low:high]``. Negative indices, as when slicing from Python, are not</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_152">152+</td><td nowrap="nowrap"><span class="diff_add"> supported.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to15__14"></td><td class="diff_header" id="to15_153">153+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_154">154+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_155">155+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` for *low* and *high*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_156">156+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_120">120</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_121">121</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_122">122</td><td nowrap="nowrap">.. cfunction:: int PyList_SetSlice(PyObject *list, Py_ssize_t low, Py_ssize_t high, PyObject *itemlist)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_123">123</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__15">n</a></td><td class="diff_header" id="from15_124">124-</td><td nowrap="nowrap"> Set the slice of *list* between *low* and *high* to the contents of<span class="diff_sub"> *itemlist*.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__15">n</a></td><td class="diff_header" id="to15_161">161+</td><td nowrap="nowrap"> Set the slice of *list* between *low* and *high* to the contents of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_125">125-</td><td nowrap="nowrap"> Analogous to ``list[low:high] = itemlist``. The *itemlist* may<span class="diff_sub"> be *NULL*,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_162">162+</td><td nowrap="nowrap"> <span class="diff_add"> *itemlist*.</span> Analogous to ``list[low:high] = itemlist``. The *itemlist* may</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_126">126-</td><td nowrap="nowrap"> indicating the assignment of an empty list (slice deletion).<span class="diff_sub"> Return ``0`` on</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_163">163+</td><td nowrap="nowrap"> <span class="diff_add"> be *NULL*,</span> indicating the assignment of an empty list (slice deletion).</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_127">127-</td><td nowrap="nowrap"><span class="diff_sub"> success, ``-1`` on failure.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_164">164+</td><td nowrap="nowrap"><span class="diff_add"> Return ``0`` on success, ``-1`` on failure. Negative indices, as when</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_165">165+</td><td nowrap="nowrap"><span class="diff_add"> slicing from Python, are not supported.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to15__15"></td><td class="diff_header" id="to15_166">166+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_167">167+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_168">168+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` for *low* and *high*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_169">169+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_128">128</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_129">129</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_130">130</td><td nowrap="nowrap">.. cfunction:: int PyList_Sort(PyObject *list)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_131">131</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to15__top">t</a></td><td class="diff_header" id="from15_132">132-</td><td nowrap="nowrap"> Sort the items of *list* in place. Return ``0`` on success, ``-1`` on<span class="diff_sub"> failure.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to15__top">t</a></td><td class="diff_header" id="to15_174">174+</td><td nowrap="nowrap"> Sort the items of *list* in place. Return ``0`` on success, ``-1`` on</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from15_133">133-</td><td nowrap="nowrap"> This is equivalent to ``list.sort()``.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to15_175">175+</td><td nowrap="nowrap"> <span class="diff_add"> failure.</span> This is equivalent to ``list.sort()``.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from15_134">134</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_135">135</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_136">136</td><td nowrap="nowrap">.. cfunction:: int PyList_Reverse(PyObject *list)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_137">137</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_138">138</td><td nowrap="nowrap"> Reverse the items of *list* in place. Return ``0`` on success, ``-1`` on</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_139">139</td><td nowrap="nowrap"> failure. This is the equivalent of ``list.reverse()``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_140">140</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from15_141">141</td><td nowrap="nowrap"></td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/long.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,31 @@ +--- r262/c-api/long.rst 2009-04-06 06:11:43.798160000 +0900 ++++ r266/c-api/long.rst 2009-04-29 17:00:05.894850000 +0900 +@@ -97,24 +97,28 @@ + + + .. cfunction:: PyObject* PyLong_FromUnicode(Py_UNICODE *u, Py_ssize_t length, int base) + + Convert a sequence of Unicode digits to a Python long integer value. The first + parameter, *u*, points to the first character of the Unicode string, *length* + gives the number of characters, and *base* is the radix for the conversion. The + radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError` + will be raised. + + .. 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) + + Create a Python integer or long integer from the pointer *p*. The pointer value + can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`. + + .. versionadded:: 1.5.2 + + .. versionchanged:: 2.5 + If the integer is larger than LONG_MAX, a positive long integer is returned. + + ======================================= --- /dev/null +++ /c-api/diff/long.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,52 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to16__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/long.rst => r266/c-api/long.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to16__0"></td><td class="diff_header" id="from16_101">101</td><td nowrap="nowrap"> Convert a sequence of Unicode digits to a Python long integer value. The first</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_102">102</td><td nowrap="nowrap"> parameter, *u*, points to the first character of the Unicode string, *length*</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_103">103</td><td nowrap="nowrap"> gives the number of characters, and *base* is the radix for the conversion. The</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_104">104</td><td nowrap="nowrap"> radix must be in the range [2, 36]; if it is out of range, :exc:`ValueError`</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_105">105</td><td nowrap="nowrap"> will be raised.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_106">106</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_107">107</td><td nowrap="nowrap"> .. versionadded:: 1.6</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_108">108</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to16__top">t</a></td><td class="diff_header" id="to16_109">109+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to16_110">110+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` for *length*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to16_111">111+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to16_112">112+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from16_109">109</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_110">110</td><td nowrap="nowrap">.. cfunction:: PyObject* PyLong_FromVoidPtr(void *p)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_111">111</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_112">112</td><td nowrap="nowrap"> Create a Python integer or long integer from the pointer *p*. The pointer value</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_113">113</td><td nowrap="nowrap"> can be retrieved from the resulting value using :cfunc:`PyLong_AsVoidPtr`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_114">114</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_115">115</td><td nowrap="nowrap"> .. versionadded:: 1.5.2</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from16_116">116</td><td nowrap="nowrap"></td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/mapping.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,41 @@ +--- r262/c-api/mapping.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/mapping.rst 2009-04-29 17:00:05.894850000 +0900 +@@ -3,32 +3,37 @@ + .. _mapping: + + Mapping Protocol + ================ + + + .. cfunction:: int PyMapping_Check(PyObject *o) + + Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This + 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 + + Returns the number of keys in object *o* on success, and ``-1`` on failure. For + 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) + + Remove the mapping for object *key* from the object *o*. Return ``-1`` on + failure. This is equivalent to the Python statement ``del o[key]``. + + + .. cfunction:: int PyMapping_DelItem(PyObject *o, PyObject *key) + + Remove the mapping for object *key* from the object *o*. Return ``-1`` on + failure. This is equivalent to the Python statement ``del o[key]``. + ======================================= --- /dev/null +++ /c-api/diff/mapping.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,55 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to17__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/mapping.rst => r266/c-api/mapping.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to17__0"></td><td class="diff_header" id="from17_7">7</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_8">8</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_9">9</td><td nowrap="nowrap">.. cfunction:: int PyMapping_Check(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_10">10</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_11">11</td><td nowrap="nowrap"> Return ``1`` if the object provides mapping protocol, and ``0`` otherwise. This</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_12">12</td><td nowrap="nowrap"> function always succeeds.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_13">13</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_14">14</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next" id="difflib_chg_to17__1"><a href="#difflib_chg_to17__1">n</a></td><td class="diff_header" id="from17_15">15-</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PyMapping_<span class="diff_chg">L</span>e<span class="diff_sub">ngth</span>(PyObject *o)</td></tr> +<tr><td class="diff_next" id="difflib_chg_to17__1"><a href="#difflib_chg_to17__1">n</a></td><td class="diff_header" id="to17_15">15+</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PyMapping_<span class="diff_chg">Siz</span>e(PyObject *o)</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to17_16">16+</td><td nowrap="nowrap"><span class="diff_add"> Py_ssize_t PyMapping_Length(PyObject *o)</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from17_16">16</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_17">17</td><td nowrap="nowrap"> .. index:: builtin: len</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_18">18</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_19">19</td><td nowrap="nowrap"> Returns the number of keys in object *o* on success, and ``-1`` on failure. For</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_20">20</td><td nowrap="nowrap"> objects that do not provide mapping protocol, this is equivalent to the Python</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_21">21</td><td nowrap="nowrap"> expression ``len(o)``.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to17__top">t</a></td><td class="diff_header" id="to17_23">23+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to17_24">24+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to17_25">25+</td><td nowrap="nowrap"><span class="diff_add"> These functions returned an :ctype:`int` type. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to17_26">26+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from17_22">22</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_23">23</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_24">24</td><td nowrap="nowrap">.. cfunction:: int PyMapping_DelItemString(PyObject *o, char *key)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_25">25</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_26">26</td><td nowrap="nowrap"> Remove the mapping for object *key* from the object *o*. Return ``-1`` on</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_27">27</td><td nowrap="nowrap"> failure. This is equivalent to the Python statement ``del o[key]``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_28">28</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from17_29">29</td><td nowrap="nowrap"></td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/marshal.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,135 @@ +--- r262/c-api/marshal.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/marshal.rst 2009-04-29 17:00:05.894850000 +0900 +@@ -1,94 +1,100 @@ + .. highlightlang:: c + + .. _marshalling-utils: + + 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. + + + .. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version) + + Marshal a Python object, *value*, to *file*. + + .. versionchanged:: 2.4 + *version* indicates the file format. + + + .. cfunction:: PyObject* PyMarshal_WriteObjectToString(PyObject *value, int version) + + Return a string object containing the marshalled representation of *value*. + + .. versionchanged:: 2.4 + *version* indicates the file format. + + + 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) + + Return a Python object from the data stream in a :ctype:`FILE\*` opened for + reading. On error, sets the appropriate exception (:exc:`EOFError` or + :exc:`TypeError`) and returns *NULL*. + + + .. 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. ======================================= --- /dev/null +++ /c-api/diff/marshal.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,120 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to18__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/marshal.rst => r266/c-api/marshal.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to18__0"><a href="#difflib_chg_to18__0">f</a></td><td class="diff_header" id="from18_1">1</td><td nowrap="nowrap">.. highlightlang:: c</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_2">2</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_3">3</td><td nowrap="nowrap">.. _marshalling-utils:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_4">4</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_5">5</td><td nowrap="nowrap">Data marshalling support</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_6">6</td><td nowrap="nowrap">========================</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_7">7</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next" id="difflib_chg_to18__1"><a href="#difflib_chg_to18__1">n</a></td><td class="diff_header" id="from18_8">8-</td><td nowrap="nowrap">These routines allow C code to work with serialized objects using the same<span class="diff_sub"> data</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to18__1"><a href="#difflib_chg_to18__1">n</a></td><td class="diff_header" id="to18_8">8+</td><td nowrap="nowrap">These routines allow C code to work with serialized objects using the same</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_9">9-</td><td nowrap="nowrap">format as the :mod:`marshal` module. There are functions to write data<span class="diff_sub"> into the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_9">9+</td><td nowrap="nowrap"><span class="diff_add">data </span>format as the :mod:`marshal` module. There are functions to write data</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_10">10-</td><td nowrap="nowrap">serialization format, and additional functions that can be used to<span class="diff_sub"> read the data</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_10">10+</td><td nowrap="nowrap"><span class="diff_add">into the </span>serialization format, and additional functions that can be used to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_11">11-</td><td nowrap="nowrap">back. Files used to store marshalled data must be opened in<span class="diff_sub"> binary mode.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_11">11+</td><td nowrap="nowrap"><span class="diff_add">read the data </span>back. Files used to store marshalled data must be opened in</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_12">12+</td><td nowrap="nowrap"><span class="diff_add">binary mode.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from18_12">12</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_13">13</td><td nowrap="nowrap">Numeric values are stored with the least significant byte first.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_14">14</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to18__2">n</a></td><td class="diff_header" id="from18_15">15-</td><td nowrap="nowrap">The module supports two versions of the data format: version 0 is the<span class="diff_sub"> historical</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to18__2">n</a></td><td class="diff_header" id="to18_16">16+</td><td nowrap="nowrap">The module supports two versions of the data format: version 0 is the</td></tr> +<tr><td class="diff_next" id="difflib_chg_to18__2"></td><td class="diff_header" id="from18_16">16-</td><td nowrap="nowrap">version, version 1 (new in Python 2.4) shares interned strings in<span class="diff_sub"> the file, and</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to18__2"></td><td class="diff_header" id="to18_17">17+</td><td nowrap="nowrap"><span class="diff_add">historical </span>version, version 1 (new in Python 2.4) shares interned strings in</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_17">17-</td><td nowrap="nowrap">upon unmarshalling. Version 2 (new in Python 2.5) uses a binary<span class="diff_sub"> format for</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_18">18+</td><td nowrap="nowrap"><span class="diff_add">the file, and </span>upon unmarshalling. Version 2 (new in Python 2.5) uses a binary</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_18">18-</td><td nowrap="nowrap"><span class="diff_sub">floating point numbers.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_19">19+</td><td nowrap="nowrap"><span class="diff_add">format for floating point numbers. *Py_MARSHAL_VERSION* indicates the current</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_19">19-</td><td nowrap="nowrap"><span class="diff_sub">*Py_MARSHAL_VERSION* indicates the current file format (currently 2).</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_20">20+</td><td nowrap="nowrap"><span class="diff_add">file format (currently 2).</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from18_20">20</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_21">21</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_22">22</td><td nowrap="nowrap">.. cfunction:: void PyMarshal_WriteLongToFile(long value, FILE *file, int version)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_23">23</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to18__3">n</a></td><td class="diff_header" id="from18_24">24-</td><td nowrap="nowrap"> Marshal a :ctype:`long` integer, *value*, to *file*. This will only write<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to18__3">n</a></td><td class="diff_header" id="to18_25">25+</td><td nowrap="nowrap"> Marshal a :ctype:`long` integer, *value*, to *file*. This will only write</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_25">25-</td><td nowrap="nowrap"> least-significant 32 bits of *value*; regardless of the size of the<span class="diff_sub"> native</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_26">26+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> least-significant 32 bits of *value*; regardless of the size of the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_26">26-</td><td nowrap="nowrap"> :ctype:`long` type.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_27">27+</td><td nowrap="nowrap"> <span class="diff_add"> native</span> :ctype:`long` type.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from18_27">27</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_28">28</td><td nowrap="nowrap"> .. versionchanged:: 2.4</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_29">29</td><td nowrap="nowrap"> *version* indicates the file format.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_30">30</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_31">31</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_32">32</td><td nowrap="nowrap">.. cfunction:: void PyMarshal_WriteObjectToFile(PyObject *value, FILE *file, int version)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_33">33</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_34">34</td><td nowrap="nowrap"> Marshal a Python object, *value*, to *file*.</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to18__3"></td><td class="diff_header" id="from18_43">43</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_44">44</td><td nowrap="nowrap"> .. versionchanged:: 2.4</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_45">45</td><td nowrap="nowrap"> *version* indicates the file format.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_46">46</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_47">47</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_48">48</td><td nowrap="nowrap">The following functions allow marshalled values to be read back in.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_49">49</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_50">50</td><td nowrap="nowrap">XXX What about error detection? It appears that reading past the end of the</td></tr><tr><td class="diff_next" id="difflib_chg_to18__4"><a href="#difflib_chg_to18__4">n</a></td><td class="diff_header" id="from18_51">51-</td><td nowrap="nowrap">file will always result in a negative numeric value (where that's relevant),<span class="diff_sub"> but</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to18__4"><a href="#difflib_chg_to18__4">n</a></td><td class="diff_header" id="to18_52">52+</td><td nowrap="nowrap">file will always result in a negative numeric value (where that's relevant),</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_52">52-</td><td nowrap="nowrap">it's not clear that negative values won't be handled properly when there's<span class="diff_sub"> no</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_53">53+</td><td nowrap="nowrap"><span class="diff_add">but </span>it's not clear that negative values won't be handled properly when there's</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_53">53-</td><td nowrap="nowrap">error. What's the right way to tell? Should only non-negative values be<span class="diff_sub"> written</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_54">54+</td><td nowrap="nowrap"><span class="diff_add">no </span>error. What's the right way to tell? Should only non-negative values be</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_54">54-</td><td nowrap="nowrap">using these routines?</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_55">55+</td><td nowrap="nowrap"><span class="diff_add">written </span>using these routines?</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from18_55">55</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_56">56</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_57">57</td><td nowrap="nowrap">.. cfunction:: long PyMarshal_ReadLongFromFile(FILE *file)</td></tr> <tr><td class="diff_next" id="difflib_chg_to18__5"></td><td class="diff_header" id="from18_58">58</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to18__5">n</a></td><td class="diff_header" id="from18_59">59-</td><td nowrap="nowrap"> Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened<span class="diff_sub"> for</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to18__5">n</a></td><td class="diff_header" id="to18_60">60+</td><td nowrap="nowrap"> Return a C :ctype:`long` from the data stream in a :ctype:`FILE\*` opened</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_60">60-</td><td nowrap="nowrap"> reading. Only a 32-bit value can be read in using this function,<span class="diff_sub"> regardless of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_61">61+</td><td nowrap="nowrap"> <span class="diff_add"> for</span> reading. Only a 32-bit value can be read in using this function,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_61">61-</td><td nowrap="nowrap"> the native size of :ctype:`long`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_62">62+</td><td nowrap="nowrap"> <span class="diff_add"> regardless of</span> the native size of :ctype:`long`.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from18_62">62</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_63">63</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_64">64</td><td nowrap="nowrap">.. cfunction:: int PyMarshal_ReadShortFromFile(FILE *file)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_65">65</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to18__6">n</a></td><td class="diff_header" id="from18_66">66-</td><td nowrap="nowrap"> Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened<span class="diff_sub"> for</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to18__6">n</a></td><td class="diff_header" id="to18_67">67+</td><td nowrap="nowrap"> Return a C :ctype:`short` from the data stream in a :ctype:`FILE\*` opened</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_67">67-</td><td nowrap="nowrap"> reading. Only a 16-bit value can be read in using this function,<span class="diff_sub"> regardless of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_68">68+</td><td nowrap="nowrap"> <span class="diff_add"> for</span> reading. Only a 16-bit value can be read in using this function,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_68">68-</td><td nowrap="nowrap"> the native size of :ctype:`short`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_69">69+</td><td nowrap="nowrap"> <span class="diff_add"> regardless of</span> the native size of :ctype:`short`.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from18_69">69</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_70">70</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_71">71</td><td nowrap="nowrap">.. cfunction:: PyObject* PyMarshal_ReadObjectFromFile(FILE *file)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_72">72</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to18__6"></td><td class="diff_header" id="from18_73">73</td><td nowrap="nowrap"> Return a Python object from the data stream in a :ctype:`FILE\*` opened for</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_74">74</td><td nowrap="nowrap"> reading. On error, sets the appropriate exception (:exc:`EOFError` or</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_75">75</td><td nowrap="nowrap"> :exc:`TypeError`) and returns *NULL*.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_76">76</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_77">77</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_78">78</td><td nowrap="nowrap">.. cfunction:: PyObject* PyMarshal_ReadLastObjectFromFile(FILE *file)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_79">79</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_80">80</td><td nowrap="nowrap"> Return a Python object from the data stream in a :ctype:`FILE\*` opened for</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to18__7">n</a></td><td class="diff_header" id="from18_81">81-</td><td nowrap="nowrap"> reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function<span class="diff_sub"> assumes</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to18__7">n</a></td><td class="diff_header" id="to18_82">82+</td><td nowrap="nowrap"> reading. Unlike :cfunc:`PyMarshal_ReadObjectFromFile`, this function</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_82">82-</td><td nowrap="nowrap"> that no further objects will be read from the file, allowing it to<span class="diff_sub"> aggressively</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_83">83+</td><td nowrap="nowrap"> <span class="diff_add"> assumes</span> that no further objects will be read from the file, allowing it to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_83">83-</td><td nowrap="nowrap"> load file data into memory so that the de-serialization can<span class="diff_sub"> operate from data in</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_84">84+</td><td nowrap="nowrap"> <span class="diff_add"> aggressively</span> load file data into memory so that the de-serialization can</td></tr> +<tr><td class="diff_next" id="difflib_chg_to18__7"></td><td class="diff_header" id="from18_84">84-</td><td nowrap="nowrap"><span class="diff_sub"> memory rather than reading a byte at a time from the file. Only use these</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to18__7"></td><td class="diff_header" id="to18_85">85+</td><td nowrap="nowrap"><span class="diff_add"> operate from data in memory rather than reading a byte at a time from the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_85">85-</td><td nowrap="nowrap"><span class="diff_sub"> variant if you are certain that you won't be reading anything else from the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_86">86+</td><td nowrap="nowrap"><span class="diff_add"> file. Only use these variant if you are certain that you won't be reading</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_86">86-</td><td nowrap="nowrap"><span class="diff_sub"> file. On error, sets the appropriate exception (:exc:`EOFError` or</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_87">87+</td><td nowrap="nowrap"><span class="diff_add"> anything else from the file. On error, sets the appropriate exception</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_87">87-</td><td nowrap="nowrap"> :exc:`TypeError`) and returns *NULL*.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_88">88+</td><td nowrap="nowrap"> <span class="diff_add"> (:exc:`EOFError` or</span> :exc:`TypeError`) and returns *NULL*.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from18_88">88</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_89">89</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_90">90</td><td nowrap="nowrap">.. cfunction:: PyObject* PyMarshal_ReadObjectFromString(char *string, Py_ssize_t len)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from18_91">91</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to18__top">t</a></td><td class="diff_header" id="from18_92">92-</td><td nowrap="nowrap"> Return a Python object from the data stream in a character buffer<span class="diff_sub"> containing</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to18__top">t</a></td><td class="diff_header" id="to18_93">93+</td><td nowrap="nowrap"> Return a Python object from the data stream in a character buffer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_93">93-</td><td nowrap="nowrap"> *len* bytes pointed to by *string*. On error, sets the<span class="diff_sub"> appropriate exception</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_94">94+</td><td nowrap="nowrap"> <span class="diff_add"> containing</span> *len* bytes pointed to by *string*. On error, sets the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from18_94">94-</td><td nowrap="nowrap"> (:exc:`EOFError` or :exc:`TypeError`) and returns<span class="diff_sub"> *NULL*.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_95">95+</td><td nowrap="nowrap"> <span class="diff_add"> appropriate exception</span> (:exc:`EOFError` or :exc:`TypeError`) and returns</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_96">96+</td><td nowrap="nowrap"><span class="diff_add"> *NULL*.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_97">97+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_98">98+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_99">99+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *len*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to18_100">100+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/method.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,21 @@ +--- r262/c-api/method.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/method.rst 2009-10-27 23:34:21.573917000 +0900 +@@ -56,17 +56,17 @@ + + .. cfunction:: PyObject* PyMethod_Self(PyObject *meth) + + Return the instance associated with the method *meth* if it is bound, otherwise + return *NULL*. + + + .. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth) + + Macro version of :cfunc:`PyMethod_Self` which avoids error checking. + + +-.. cfunction:: int PyMethod_ClearFreeList(void) ++.. cfunction:: int PyMethod_ClearFreeList() + + Clear the free list. Return the total number of freed items. + + .. versionadded:: 2.6 ======================================= --- /dev/null +++ /c-api/diff/method.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,50 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to19__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/method.rst => r266/c-api/method.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to19__0"></td><td class="diff_header" id="from19_60">60</td><td nowrap="nowrap"> return *NULL*.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_61">61</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_62">62</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_63">63</td><td nowrap="nowrap">.. cfunction:: PyObject* PyMethod_GET_SELF(PyObject *meth)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_64">64</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_65">65</td><td nowrap="nowrap"> Macro version of :cfunc:`PyMethod_Self` which avoids error checking.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_66">66</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_67">67</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to19__top">t</a></td><td class="diff_header" id="from19_68">68-</td><td nowrap="nowrap">.. cfunction:: int PyMethod_ClearFreeList(<span class="diff_sub">void</span>)</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to19__top">t</a></td><td class="diff_header" id="to19_68">68+</td><td nowrap="nowrap">.. cfunction:: int PyMethod_ClearFreeList()</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from19_69">69</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_70">70</td><td nowrap="nowrap"> Clear the free list. Return the total number of freed items.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_71">71</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from19_72">72</td><td nowrap="nowrap"> .. versionadded:: 2.6</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/objbuffer.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,81 @@ +--- r262/c-api/objbuffer.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/objbuffer.rst 2009-04-29 17:00:05.894850000 +0900 +@@ -1,46 +1,66 @@ + .. highlightlang:: c + + .. _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) + + Returns ``1`` if *o* supports the single-segment readable buffer interface. + Otherwise returns ``0``. + + .. versionadded:: 2.2 + + + .. 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. ++ ======================================= --- /dev/null +++ /c-api/diff/objbuffer.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,92 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to20__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/objbuffer.rst => r266/c-api/objbuffer.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to20__0"><a href="#difflib_chg_to20__0">f</a></td><td class="diff_header" id="from20_1">1</td><td nowrap="nowrap">.. highlightlang:: c</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_2">2</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_3">3</td><td nowrap="nowrap">.. _abstract-buffer:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_4">4</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to20__1">n</a></td><td class="diff_header" id="from20_5">5-</td><td nowrap="nowrap">Buffer Protocol</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to20__1">n</a></td><td class="diff_header" id="to20_5">5+</td><td nowrap="nowrap"><span class="diff_add">Old </span>Buffer Protocol</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from20_6">6-</td><td nowrap="nowrap">===============</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_6">6+</td><td nowrap="nowrap">===============<span class="diff_add">====</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_7">7+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_8">8+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_9">9+</td><td nowrap="nowrap"><span class="diff_add">This section describes the legacy buffer protocol, which has been introduced</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_10">10+</td><td nowrap="nowrap"><span class="diff_add">in Python 1.6. It is still supported but deprecated in the Python 2.x series.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_11">11+</td><td nowrap="nowrap"><span class="diff_add">Python 3.0 introduces a new buffer protocol which fixes weaknesses and</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to20__1"></td><td class="diff_header" id="to20_12">12+</td><td nowrap="nowrap"><span class="diff_add">shortcomings of the protocol, and has been backported to Python 2.6. See</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_13">13+</td><td nowrap="nowrap"><span class="diff_add">:ref:`bufferobjects` for more information.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from20_7">7</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_8">8</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_9">9</td><td nowrap="nowrap">.. cfunction:: int PyObject_AsCharBuffer(PyObject *obj, const char **buffer, Py_ssize_t *buffer_len)</td></tr> <tr><td class="diff_next" id="difflib_chg_to20__2"></td><td class="diff_header" id="from20_10">10</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_11">11</td><td nowrap="nowrap"> Returns a pointer to a read-only memory location usable as character-based</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_12">12</td><td nowrap="nowrap"> input. The *obj* argument must support the single-segment character buffer</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to20__2">n</a></td><td class="diff_header" id="from20_13">13-</td><td nowrap="nowrap"> interface. On success, returns ``0``, sets *buffer* to the memory location<span class="diff_sub"> and</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to20__2">n</a></td><td class="diff_header" id="to20_20">20+</td><td nowrap="nowrap"> interface. On success, returns ``0``, sets *buffer* to the memory location</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from20_14">14-</td><td nowrap="nowrap"> *buffer_len* to the buffer length. Returns ``-1`` and sets a<span class="diff_sub"> :exc:`TypeError`</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_21">21+</td><td nowrap="nowrap"> <span class="diff_add"> and</span> *buffer_len* to the buffer length. Returns ``-1`` and sets a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from20_15">15-</td><td nowrap="nowrap"><span class="diff_sub"> on error.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_22">22+</td><td nowrap="nowrap"><span class="diff_add"> :exc:`TypeError` on error.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from20_16">16</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_17">17</td><td nowrap="nowrap"> .. versionadded:: 1.6</td></tr><tr><td class="diff_next" id="difflib_chg_to20__3"><a href="#difflib_chg_to20__3">n</a></td><td class="diff_header" id="to20_25">25+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_26">26+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_27">27+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int *` type for *buffer_len*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_28">28+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from20_18">18</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_19">19</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_20">20</td><td nowrap="nowrap">.. cfunction:: int PyObject_AsReadBuffer(PyObject *obj, const void **buffer, Py_ssize_t *buffer_len)</td></tr> <tr><td class="diff_next" id="difflib_chg_to20__4"></td><td class="diff_header" id="from20_21">21</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to20__4">n</a></td><td class="diff_header" id="from20_22">22-</td><td nowrap="nowrap"> Returns a pointer to a read-only memory location containing arbitrary data.<span class="diff_sub"> The</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to20__4">n</a></td><td class="diff_header" id="to20_33">33+</td><td nowrap="nowrap"> Returns a pointer to a read-only memory location containing arbitrary data.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from20_23">23-</td><td nowrap="nowrap"> *obj* argument must support the single-segment readable buffer<span class="diff_sub"> interface. On</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_34">34+</td><td nowrap="nowrap"> <span class="diff_add"> The</span> *obj* argument must support the single-segment readable buffer</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from20_24">24-</td><td nowrap="nowrap"> success, returns ``0``, sets *buffer* to the memory location<span class="diff_sub"> and *buffer_len* to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_35">35+</td><td nowrap="nowrap"> <span class="diff_add"> interface. On</span> success, returns ``0``, sets *buffer* to the memory location</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from20_25">25-</td><td nowrap="nowrap"><span class="diff_sub"> the buffer length. Returns ``-1`` and sets a :exc:`TypeError` on error.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_36">36+</td><td nowrap="nowrap"><span class="diff_add"> and *buffer_len* to the buffer length. Returns ``-1`` and sets a</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_37">37+</td><td nowrap="nowrap"><span class="diff_add"> :exc:`TypeError` on error.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from20_26">26</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_27">27</td><td nowrap="nowrap"> .. versionadded:: 1.6</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to20__5">n</a></td><td class="diff_header" id="to20_40">40+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_41">41+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_42">42+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int *` type for *buffer_len*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_43">43+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from20_28">28</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_29">29</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_30">30</td><td nowrap="nowrap">.. cfunction:: int PyObject_CheckReadBuffer(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_31">31</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_32">32</td><td nowrap="nowrap"> Returns ``1`` if *o* supports the single-segment readable buffer interface.</td></tr> <tr><td class="diff_next" id="difflib_chg_to20__5"></td><td class="diff_header" id="from20_33">33</td><td nowrap="nowrap"> Otherwise returns ``0``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_34">34</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_35">35</td><td nowrap="nowrap"> .. versionadded:: 2.2</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_36">36</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_37">37</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_38">38</td><td nowrap="nowrap">.. cfunction:: int PyObject_AsWriteBuffer(PyObject *obj, void **buffer, Py_ssize_t *buffer_len)</td></tr> <tr><td class="diff_next" id="difflib_chg_to20__6"></td><td class="diff_header" id="from20_39">39</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_40">40</td><td nowrap="nowrap"> Returns a pointer to a writeable memory location. The *obj* argument must</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to20__6">n</a></td><td class="diff_header" id="from20_41">41-</td><td nowrap="nowrap"> support the single-segment, character buffer interface. On success,<span class="diff_sub"> returns</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to20__6">n</a></td><td class="diff_header" id="to20_57">57+</td><td nowrap="nowrap"> support the single-segment, character buffer interface. On success,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from20_42">42-</td><td nowrap="nowrap"> ``0``, sets *buffer* to the memory location and *buffer_len* to the<span class="diff_sub"> buffer</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_58">58+</td><td nowrap="nowrap"> <span class="diff_add"> returns</span> ``0``, sets *buffer* to the memory location and *buffer_len* to the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from20_43">43-</td><td nowrap="nowrap"> length. Returns ``-1`` and sets a :exc:`TypeError` on error.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_59">59+</td><td nowrap="nowrap"> <span class="diff_add"> buffer</span> length. Returns ``-1`` and sets a :exc:`TypeError` on error.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from20_44">44</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_45">45</td><td nowrap="nowrap"> .. versionadded:: 1.6</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from20_46">46</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to20__top">t</a></td><td class="diff_header" id="to20_63">63+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_64">64+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int *` type for *buffer_len*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_65">65+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to20_66">66+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/object.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,31 @@ +--- r262/c-api/object.rst 2009-04-06 09:24:29.561602000 +0900 ++++ r266/c-api/object.rst 2009-04-29 17:00:05.894850000 +0900 +@@ -342,24 +342,28 @@ + .. versionadded:: 2.2 + + + .. cfunction:: Py_ssize_t PyObject_Length(PyObject *o) + Py_ssize_t PyObject_Size(PyObject *o) + + .. index:: builtin: len + + Return the length of object *o*. If the object *o* provides either the sequence + 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) + + Return element of *o* corresponding to the object *key* or *NULL* on failure. + This is the equivalent of the Python expression ``o[key]``. + + + .. cfunction:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v) + + Map the object *key* to the value *v*. Returns ``-1`` on failure. This is the + equivalent of the Python statement ``o[key] = v``. + ======================================= --- /dev/null +++ /c-api/diff/object.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,52 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to21__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/object.rst => r266/c-api/object.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to21__0"></td><td class="diff_header" id="from21_346">346</td><td nowrap="nowrap"> Py_ssize_t PyObject_Size(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_347">347</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_348">348</td><td nowrap="nowrap"> .. index:: builtin: len</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_349">349</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_350">350</td><td nowrap="nowrap"> Return the length of object *o*. If the object *o* provides either the sequence</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_351">351</td><td nowrap="nowrap"> and mapping protocols, the sequence length is returned. On error, ``-1`` is</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_352">352</td><td nowrap="nowrap"> returned. This is the equivalent to the Python expression ``len(o)``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_353">353</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to21__top">t</a></td><td class="diff_header" id="to21_354">354+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to21_355">355+</td><td nowrap="nowrap"><span class="diff_add"> These functions returned an :ctype:`int` type. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to21_356">356+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to21_357">357+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from21_354">354</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_355">355</td><td nowrap="nowrap">.. cfunction:: PyObject* PyObject_GetItem(PyObject *o, PyObject *key)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_356">356</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_357">357</td><td nowrap="nowrap"> Return element of *o* corresponding to the object *key* or *NULL* on failure.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_358">358</td><td nowrap="nowrap"> This is the equivalent of the Python expression ``o[key]``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_359">359</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_360">360</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from21_361">361</td><td nowrap="nowrap">.. cfunction:: int PyObject_SetItem(PyObject *o, PyObject *key, PyObject *v)</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/sequence.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,225 @@ +--- r262/c-api/sequence.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/sequence.rst 2009-10-27 23:19:50.039185000 +0900 +@@ -4,119 +4,159 @@ + + Sequence Protocol + ================= + + + .. cfunction:: int PySequence_Check(PyObject *o) + + Return ``1`` if the object provides sequence protocol, and ``0`` otherwise. + This function always succeeds. + + + .. cfunction:: Py_ssize_t PySequence_Size(PyObject *o) ++ Py_ssize_t PySequence_Length(PyObject *o) + + .. index:: builtin: len + + Returns the number of objects in sequence *o* on success, and ``-1`` on failure. + 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) + + Return the concatenation of *o1* and *o2* on success, and *NULL* on failure. + This is the equivalent of the Python expression ``o1 + o2``. + + + .. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count) + + 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) + + Return the concatenation of *o1* and *o2* on success, and *NULL* on failure. + The operation is done *in-place* when *o1* supports it. This is the equivalent + of the Python expression ``o1 += o2``. + + + .. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count) + + Return the result of repeating sequence object *o* *count* times, or *NULL* on + 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 ++ 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) + +- Assign object *v* to the *i*th element of *o*. Returns ``-1`` on failure. This ++ Assign object *v* to the *i*\ th element of *o*. Returns ``-1`` on failure. This + 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 ++ 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) + + Return the number of occurrences of *value* in *o*, that is, return the number + 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) + + Determine if *o* contains *value*. If an item in *o* is equal to *value*, + return ``1``, otherwise return ``0``. On error, return ``-1``. This is + equivalent to the Python expression ``value in o``. + + + .. cfunction:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value) + + 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) + + Return a list object with the same contents as the arbitrary sequence *o*. The + returned list is guaranteed to be new. + + + .. cfunction:: PyObject* PySequence_Tuple(PyObject *o) + + .. index:: builtin: tuple + + Return a tuple object with the same contents as the arbitrary sequence *o* or +@@ -126,45 +166,53 @@ + + + .. cfunction:: PyObject* PySequence_Fast(PyObject *o, const char *m) + + Returns the sequence *o* as a tuple, unless it is already a tuple or list, in + which case *o* is returned. Use :cfunc:`PySequence_Fast_GET_ITEM` to access the + members of the result. Returns *NULL* on failure. If the object is not a + sequence, raises :exc:`TypeError` with *m* as the message text. + + + .. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i) + +- Return the *i*th element of *o*, assuming that *o* was returned by ++ 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) + + Return the underlying array of PyObject pointers. Assumes that *o* was returned + by :cfunc:`PySequence_Fast` and *o* is not *NULL*. + + Note, if a list gets resized, the reallocation may relocate the items array. + So, only use the underlying array pointer in contexts where the sequence + cannot change. + + .. versionadded:: 2.4 + + + .. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i) + +- Return the *i*th element of *o* or *NULL* on failure. Macro form of ++ Return the *i*\ th element of *o* or *NULL* on failure. Macro form of + :cfunc:`PySequence_GetItem` but without checking that + :cfunc:`PySequence_Check(o)` is true and without adjustment for negative + indices. + + .. 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) + + Returns the length of *o*, assuming that *o* was returned by + :cfunc:`PySequence_Fast` and that *o* is not *NULL*. The size can also be + gotten by calling :cfunc:`PySequence_Size` on *o*, but + :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list + or tuple. ======================================= --- /dev/null +++ /c-api/diff/sequence.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,116 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to22__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/sequence.rst => r266/c-api/sequence.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to22__0"></td><td class="diff_header" id="from22_8">8</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_9">9</td><td nowrap="nowrap">.. cfunction:: int PySequence_Check(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_10">10</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_11">11</td><td nowrap="nowrap"> Return ``1`` if the object provides sequence protocol, and ``0`` otherwise.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_12">12</td><td nowrap="nowrap"> This function always succeeds.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_13">13</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_14">14</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_15">15</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PySequence_Size(PyObject *o)</td></tr><tr><td class="diff_next" id="difflib_chg_to22__1"><a href="#difflib_chg_to22__1">n</a></td><td class="diff_header" id="to22_16">16+</td><td nowrap="nowrap"><span class="diff_add"> Py_ssize_t PySequence_Length(PyObject *o)</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_16">16</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_17">17</td><td nowrap="nowrap"> .. index:: builtin: len</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_18">18</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_19">19</td><td nowrap="nowrap"> Returns the number of objects in sequence *o* on success, and ``-1`` on failure.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_20">20</td><td nowrap="nowrap"> For objects that do not provide sequence protocol, this is equivalent to the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_21">21</td><td nowrap="nowrap"> Python expression ``len(o)``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_22">22</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__2">n</a></td><td class="diff_header" id="from22_23">23-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to22__2">n</a></td><td class="diff_header" id="to22_24">24+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from22_24">24-</td><td nowrap="nowrap"><span class="diff_sub">.. cfunction:: Py_ssize_t PySequence_Length(PyObject *o)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_25">25+</td><td nowrap="nowrap"><span class="diff_add"> These functions returned an :ctype:`int` type. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from22_25">25-</td><td nowrap="nowrap"><span class="diff_sub"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_26">26+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from22_26">26-</td><td nowrap="nowrap"><span class="diff_sub"> Alternate name for :cfunc:`PySequence_Size`.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_27">27</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_28">28</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_29">29</td><td nowrap="nowrap">.. cfunction:: PyObject* PySequence_Concat(PyObject *o1, PyObject *o2)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_30">30</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to22__2"></td><td class="diff_header" id="from22_31">31</td><td nowrap="nowrap"> Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_32">32</td><td nowrap="nowrap"> This is the equivalent of the Python expression ``o1 + o2``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_33">33</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_34">34</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_35">35</td><td nowrap="nowrap">.. cfunction:: PyObject* PySequence_Repeat(PyObject *o, Py_ssize_t count)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_36">36</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_37">37</td><td nowrap="nowrap"> Return the result of repeating sequence object *o* *count* times, or *NULL* on</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_38">38</td><td nowrap="nowrap"> failure. This is the equivalent of the Python expression ``o * count``.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__3">n</a></td><td class="diff_header" id="to22_39">39+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_40">40+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_41">41+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *count*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_42">42+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_39">39</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_40">40</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_41">41</td><td nowrap="nowrap">.. cfunction:: PyObject* PySequence_InPlaceConcat(PyObject *o1, PyObject *o2)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_42">42</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_43">43</td><td nowrap="nowrap"> Return the concatenation of *o1* and *o2* on success, and *NULL* on failure.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_44">44</td><td nowrap="nowrap"> The operation is done *in-place* when *o1* supports it. This is the equivalent</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_45">45</td><td nowrap="nowrap"> of the Python expression ``o1 += o2``.</td></tr> <tr><td class="diff_next" id="difflib_chg_to22__3"></td><td class="diff_header" id="from22_46">46</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_47">47</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_48">48</td><td nowrap="nowrap">.. cfunction:: PyObject* PySequence_InPlaceRepeat(PyObject *o, Py_ssize_t count)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_49">49</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_50">50</td><td nowrap="nowrap"> Return the result of repeating sequence object *o* *count* times, or *NULL* on</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_51">51</td><td nowrap="nowrap"> failure. The operation is done *in-place* when *o* supports it. This is the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_52">52</td><td nowrap="nowrap"> equivalent of the Python expression ``o *= count``.</td></tr> <tr><td class="diff_next" id="difflib_chg_to22__4"></td><td class="diff_header" id="from22_53">53</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__4">n</a></td><td class="diff_header" id="to22_58">58+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to22__5"></td><td class="diff_header" id="to22_59">59+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *count*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_60">60+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_61">61+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_54">54</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_55">55</td><td nowrap="nowrap">.. cfunction:: PyObject* PySequence_GetItem(PyObject *o, Py_ssize_t i)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_56">56</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__5">n</a></td><td class="diff_header" id="from22_57">57-</td><td nowrap="nowrap"> Return the *i*th element of *o*, or *NULL* on failure. This is the equivalent of</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to22__5">n</a></td><td class="diff_header" id="to22_65">65+</td><td nowrap="nowrap"> Return the *i*<span class="diff_add">\ </span>th element of *o*, or *NULL* on failure. This is the equivalent of</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_58">58</td><td nowrap="nowrap"> the Python expression ``o[i]``.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__6">n</a></td><td class="diff_header" id="to22_67">67+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_68">68+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_69">69+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *i*. This might require</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to22__6"></td><td class="diff_header" id="to22_70">70+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_59">59</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_60">60</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_61">61</td><td nowrap="nowrap">.. cfunction:: PyObject* PySequence_GetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_62">62</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_63">63</td><td nowrap="nowrap"> Return the slice of sequence object *o* between *i1* and *i2*, or *NULL* on</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_64">64</td><td nowrap="nowrap"> failure. This is the equivalent of the Python expression ``o[i1:i2]``.</td></tr> <tr><td class="diff_next" id="difflib_chg_to22__7"></td><td class="diff_header" id="from22_65">65</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__7">n</a></td><td class="diff_header" id="to22_78">78+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_79">79+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *i1* and *i2*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_80">80+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to22__8"></td><td class="diff_header" id="to22_81">81+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_66">66</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_67">67</td><td nowrap="nowrap">.. cfunction:: int PySequence_SetItem(PyObject *o, Py_ssize_t i, PyObject *v)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_68">68</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__8">n</a></td><td class="diff_header" id="from22_69">69-</td><td nowrap="nowrap"> Assign object *v* to the *i*th element of *o*. Returns ``-1`` on failure. This</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to22__8">n</a></td><td class="diff_header" id="to22_85">85+</td><td nowrap="nowrap"> Assign object *v* to the *i*<span class="diff_add">\ </span>th element of *o*. Returns ``-1`` on failure. This</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_70">70</td><td nowrap="nowrap"> is the equivalent of the Python statement ``o[i] = v``. This function *does</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_71">71</td><td nowrap="nowrap"> not* steal a reference to *v*.</td></tr> <tr><td class="diff_next" id="difflib_chg_to22__9"></td><td class="diff_header" id="from22_72">72</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__9">n</a></td><td class="diff_header" id="to22_89">89+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to22__10"></td><td class="diff_header" id="to22_90">90+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *i*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_91">91+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_92">92+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_73">73</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_74">74</td><td nowrap="nowrap">.. cfunction:: int PySequence_DelItem(PyObject *o, Py_ssize_t i)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_75">75</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__10">n</a></td><td class="diff_header" id="from22_76">76-</td><td nowrap="nowrap"> Delete the *i*th element of object *o*. Returns ``-1`` on failure. This is the</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to22__10">n</a></td><td class="diff_header" id="to22_96">96+</td><td nowrap="nowrap"> Delete the *i*<span class="diff_add">\ </span>th element of object *o*. Returns ``-1`` on failure. This is the</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_77">77</td><td nowrap="nowrap"> equivalent of the Python statement ``del o[i]``.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__11">n</a></td><td class="diff_header" id="to22_98">98+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_99">99+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_100">100+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *i*. This might require</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to22__11"></td><td class="diff_header" id="to22_101">101+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_78">78</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_79">79</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_80">80</td><td nowrap="nowrap">.. cfunction:: int PySequence_SetSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2, PyObject *v)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_81">81</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_82">82</td><td nowrap="nowrap"> Assign the sequence object *v* to the slice in sequence object *o* from *i1* to</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_83">83</td><td nowrap="nowrap"> *i2*. This is the equivalent of the Python statement ``o[i1:i2] = v``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_84">84</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__12">n</a></td><td class="diff_header" id="to22_109">109+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to22__12"></td><td class="diff_header" id="to22_110">110+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *i1* and *i2*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_111">111+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_112">112+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_85">85</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_86">86</td><td nowrap="nowrap">.. cfunction:: int PySequence_DelSlice(PyObject *o, Py_ssize_t i1, Py_ssize_t i2)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_87">87</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_88">88</td><td nowrap="nowrap"> Delete the slice in sequence object *o* from *i1* to *i2*. Returns ``-1`` on</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_89">89</td><td nowrap="nowrap"> failure. This is the equivalent of the Python statement ``del o[i1:i2]``.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__13">n</a></td><td class="diff_header" id="to22_118">118+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_119">119+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_120">120+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *i1* and *i2*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_121">121+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to22__13"></td><td class="diff_header" id="from22_90">90</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_91">91</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_92">92</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PySequence_Count(PyObject *o, PyObject *value)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_93">93</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_94">94</td><td nowrap="nowrap"> Return the number of occurrences of *value* in *o*, that is, return the number</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_95">95</td><td nowrap="nowrap"> of keys for which ``o[key] == value``. On failure, return ``-1``. This is</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_96">96</td><td nowrap="nowrap"> equivalent to the Python expression ``o.count(value)``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_97">97</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__14">n</a></td><td class="diff_header" id="to22_130">130+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_131">131+</td><td nowrap="nowrap"><span class="diff_add"> This function returned an :ctype:`int` type. This might require changes</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_132">132+</td><td nowrap="nowrap"><span class="diff_add"> in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_133">133+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_98">98</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_99">99</td><td nowrap="nowrap">.. cfunction:: int PySequence_Contains(PyObject *o, PyObject *value)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_100">100</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_101">101</td><td nowrap="nowrap"> Determine if *o* contains *value*. If an item in *o* is equal to *value*,</td></tr> <tr><td class="diff_next" id="difflib_chg_to22__14"></td><td class="diff_header" id="from22_102">102</td><td nowrap="nowrap"> return ``1``, otherwise return ``0``. On error, return ``-1``. This is</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_103">103</td><td nowrap="nowrap"> equivalent to the Python expression ``value in o``.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_104">104</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_105">105</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_106">106</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PySequence_Index(PyObject *o, PyObject *value)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_107">107</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_108">108</td><td nowrap="nowrap"> Return the first index *i* for which ``o[i] == value``. On error, return</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_109">109</td><td nowrap="nowrap"> ``-1``. This is equivalent to the Python expression ``o.index(value)``.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__15">n</a></td><td class="diff_header" id="to22_146">146+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_147">147+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_148">148+</td><td nowrap="nowrap"><span class="diff_add"> This function returned an :ctype:`int` type. This might require changes</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_149">149+</td><td nowrap="nowrap"><span class="diff_add"> in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_110">110</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_111">111</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_112">112</td><td nowrap="nowrap">.. cfunction:: PyObject* PySequence_List(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_113">113</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_114">114</td><td nowrap="nowrap"> Return a list object with the same contents as the arbitrary sequence *o*. The</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_115">115</td><td nowrap="nowrap"> returned list is guaranteed to be new.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_116">116</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_117">117</td><td nowrap="nowrap"></td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to22__15"></td><td class="diff_header" id="from22_130">130</td><td nowrap="nowrap"> Returns the sequence *o* as a tuple, unless it is already a tuple or list, in</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_131">131</td><td nowrap="nowrap"> which case *o* is returned. Use :cfunc:`PySequence_Fast_GET_ITEM` to access the</td></tr> <tr><td class="diff_next" id="difflib_chg_to22__16"></td><td class="diff_header" id="from22_132">132</td><td nowrap="nowrap"> members of the result. Returns *NULL* on failure. If the object is not a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_133">133</td><td nowrap="nowrap"> sequence, raises :exc:`TypeError` with *m* as the message text.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_134">134</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_135">135</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_136">136</td><td nowrap="nowrap">.. cfunction:: PyObject* PySequence_Fast_GET_ITEM(PyObject *o, Py_ssize_t i)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_137">137</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__16">n</a></td><td class="diff_header" id="from22_138">138-</td><td nowrap="nowrap"> Return the *i*th element of *o*, assuming that *o* was returned by</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to22__16">n</a></td><td class="diff_header" id="to22_178">178+</td><td nowrap="nowrap"> Return the *i*<span class="diff_add">\ </span>th element of *o*, assuming that *o* was returned by</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_139">139</td><td nowrap="nowrap"> :cfunc:`PySequence_Fast`, *o* is not *NULL*, and that *i* is within bounds.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__17">n</a></td><td class="diff_header" id="to22_180">180+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_181">181+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_182">182+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *i*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_183">183+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_140">140</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_141">141</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_142">142</td><td nowrap="nowrap">.. cfunction:: PyObject** PySequence_Fast_ITEMS(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_143">143</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_144">144</td><td nowrap="nowrap"> Return the underlying array of PyObject pointers. Assumes that *o* was returned</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_145">145</td><td nowrap="nowrap"> by :cfunc:`PySequence_Fast` and *o* is not *NULL*.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_146">146</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_147">147</td><td nowrap="nowrap"> Note, if a list gets resized, the reallocation may relocate the items array.</td></tr> <tr><td class="diff_next" id="difflib_chg_to22__17"></td><td class="diff_header" id="from22_148">148</td><td nowrap="nowrap"> So, only use the underlying array pointer in contexts where the sequence</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_149">149</td><td nowrap="nowrap"> cannot change.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_150">150</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_151">151</td><td nowrap="nowrap"> .. versionadded:: 2.4</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_152">152</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_153">153</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to22__18"></td><td class="diff_header" id="from22_154">154</td><td nowrap="nowrap">.. cfunction:: PyObject* PySequence_ITEM(PyObject *o, Py_ssize_t i)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_155">155</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__18">n</a></td><td class="diff_header" id="from22_156">156-</td><td nowrap="nowrap"> Return the *i*th element of *o* or *NULL* on failure. Macro form of</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to22__18">n</a></td><td class="diff_header" id="to22_200">200+</td><td nowrap="nowrap"> Return the *i*<span class="diff_add">\ </span>th element of *o* or *NULL* on failure. Macro form of</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_157">157</td><td nowrap="nowrap"> :cfunc:`PySequence_GetItem` but without checking that</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_158">158</td><td nowrap="nowrap"> :cfunc:`PySequence_Check(o)` is true and without adjustment for negative</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_159">159</td><td nowrap="nowrap"> indices.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_160">160</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_161">161</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to22__top">t</a></td><td class="diff_header" id="to22_206">206+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_207">207+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_208">208+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *i*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to22_209">209+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from22_162">162</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_163">163</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_164">164</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PySequence_Fast_GET_SIZE(PyObject *o)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_165">165</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_166">166</td><td nowrap="nowrap"> Returns the length of *o*, assuming that *o* was returned by</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_167">167</td><td nowrap="nowrap"> :cfunc:`PySequence_Fast` and that *o* is not *NULL*. The size can also be</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_168">168</td><td nowrap="nowrap"> gotten by calling :cfunc:`PySequence_Size` on *o*, but</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from22_169">169</td><td nowrap="nowrap"> :cfunc:`PySequence_Fast_GET_SIZE` is faster because it can assume *o* is a list</td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/set.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,31 @@ +--- r262/c-api/set.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/set.rst 2009-04-29 17:00:05.894850000 +0900 +@@ -107,24 +107,28 @@ + The following functions and macros are available for instances of :class:`set` + or :class:`frozenset` or instances of their subtypes. + + + .. cfunction:: Py_ssize_t PySet_Size(PyObject *anyset) + + .. index:: builtin: len + + Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to + ``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) + + Macro form of :cfunc:`PySet_Size` without error checking. + + + .. cfunction:: int PySet_Contains(PyObject *anyset, PyObject *key) + + Return 1 if found, 0 if not found, and -1 if an error is encountered. Unlike + the Python :meth:`__contains__` method, this function does not automatically + convert unhashable sets into temporary frozensets. Raise a :exc:`TypeError` if + the *key* is unhashable. Raise :exc:`PyExc_SystemError` if *anyset* is not a ======================================= --- /dev/null +++ /c-api/diff/set.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,52 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to23__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/set.rst => r266/c-api/set.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to23__0"></td><td class="diff_header" id="from23_111">111</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PySet_Size(PyObject *anyset)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_112">112</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_113">113</td><td nowrap="nowrap"> .. index:: builtin: len</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_114">114</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_115">115</td><td nowrap="nowrap"> Return the length of a :class:`set` or :class:`frozenset` object. Equivalent to</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_116">116</td><td nowrap="nowrap"> ``len(anyset)``. Raises a :exc:`PyExc_SystemError` if *anyset* is not a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_117">117</td><td nowrap="nowrap"> :class:`set`, :class:`frozenset`, or an instance of a subtype.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_118">118</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to23__top">t</a></td><td class="diff_header" id="to23_119">119+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to23_120">120+</td><td nowrap="nowrap"><span class="diff_add"> This function returned an :ctype:`int`. This might require changes in</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to23_121">121+</td><td nowrap="nowrap"><span class="diff_add"> your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to23_122">122+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from23_119">119</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_120">120</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PySet_GET_SIZE(PyObject *anyset)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_121">121</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_122">122</td><td nowrap="nowrap"> Macro form of :cfunc:`PySet_Size` without error checking.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_123">123</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_124">124</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_125">125</td><td nowrap="nowrap">.. cfunction:: int PySet_Contains(PyObject *anyset, PyObject *key)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from23_126">126</td><td nowrap="nowrap"></td></tr> </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/slice.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,77 @@ +--- r262/c-api/slice.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/slice.rst 2009-04-29 17:00:05.894850000 +0900 +@@ -13,44 +13,56 @@ + The type object for slice objects. This is the same as ``slice`` and + ``types.SliceType``. + + + .. cfunction:: int PySlice_Check(PyObject *ob) + + Return true if *ob* is a slice object; *ob* must not be *NULL*. + + + .. 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). +- +- 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. ++ 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. ++ ++ .. 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. ======================================= --- /dev/null +++ /c-api/diff/slice.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,94 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to24__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/slice.rst => r266/c-api/slice.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to24__0"></td><td class="diff_header" id="from24_17">17</td><td nowrap="nowrap">.. cfunction:: int PySlice_Check(PyObject *ob)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_18">18</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_19">19</td><td nowrap="nowrap"> Return true if *ob* is a slice object; *ob* must not be *NULL*.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_20">20</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_21">21</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_22">22</td><td nowrap="nowrap">.. cfunction:: PyObject* PySlice_New(PyObject *start, PyObject *stop, PyObject *step)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_23">23</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_24">24</td><td nowrap="nowrap"> Return a new slice object with the given values. The *start*, *stop*, and</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to24__1">n</a></td><td class="diff_header" id="from24_25">25-</td><td nowrap="nowrap"> *step* parameters are used as the values of the slice object attributes of<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to24__1">n</a></td><td class="diff_header" id="to24_25">25+</td><td nowrap="nowrap"> *step* parameters are used as the values of the slice object attributes of</td></tr> +<tr><td class="diff_next" id="difflib_chg_to24__1"></td><td class="diff_header" id="from24_26">26-</td><td nowrap="nowrap"> same names. Any of the values may be *NULL*, in which case the<span class="diff_sub"> ``None`` will be</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to24__1"></td><td class="diff_header" id="to24_26">26+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> same names. Any of the values may be *NULL*, in which case the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_27">27-</td><td nowrap="nowrap"><span class="diff_sub"> used for the corresponding attribute. Return *NULL* if the new object could not</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_27">27+</td><td nowrap="nowrap"><span class="diff_add"> ``None`` will be used for the corresponding attribute. Return *NULL* if</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_28">28-</td><td nowrap="nowrap"><span class="diff_sub"> be allocated.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_28">28+</td><td nowrap="nowrap"><span class="diff_add"> the new object could not be allocated.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to24__2"></td><td class="diff_header" id="from24_29">29</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_30">30</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_31">31</td><td nowrap="nowrap">.. cfunction:: int PySlice_GetIndices(PySliceObject *slice, Py_ssize_t length, Py_ssize_t *start, Py_ssize_t *stop, Py_ssize_t *step)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_32">32</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to24__3"></td><td class="diff_header" id="from24_33">33</td><td nowrap="nowrap"> Retrieve the start, stop and step indices from the slice object *slice*,</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to24__2">n</a></td><td class="diff_header" id="from24_34">34-</td><td nowrap="nowrap"> assuming a sequence of length *length*. Treats indices greater than<span class="diff_sub"> *length* as</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to24__2">n</a></td><td class="diff_header" id="to24_34">34+</td><td nowrap="nowrap"> assuming a sequence of length *length*. Treats indices greater than</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_35">35-</td><td nowrap="nowrap"><span class="diff_sub"> errors.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_35">35+</td><td nowrap="nowrap"><span class="diff_add"> *length* as errors.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from24_36">36</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to24__3">n</a></td><td class="diff_header" id="from24_37">37-</td><td nowrap="nowrap"> Returns 0 on success and -1 on error with no exception set (unless one of<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to24__3">n</a></td><td class="diff_header" id="to24_37">37+</td><td nowrap="nowrap"> Returns 0 on success and -1 on error with no exception set (unless one of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_38">38-</td><td nowrap="nowrap"> indices was not :const:`None` and failed to be converted to an integer,<span class="diff_sub"> in which</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_38">38+</td><td nowrap="nowrap"> <span class="diff_add"> the</span> indices was not :const:`None` and failed to be converted to an integer,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_39">39-</td><td nowrap="nowrap"> case -1 is returned with an exception set).</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_39">39+</td><td nowrap="nowrap"> <span class="diff_add"> in which</span> case -1 is returned with an exception set).</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from24_40">40</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to24__4">n</a></td><td class="diff_header" id="from24_41">41-</td><td nowrap="nowrap"> You probably do not want to use this function. If you want to use slice<span class="diff_sub"> objects</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to24__4">n</a></td><td class="diff_header" id="to24_41">41+</td><td nowrap="nowrap"> You probably do not want to use this function. If you want to use slice</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_42">42-</td><td nowrap="nowrap"> in versions of Python prior to 2.3, you would probably do well to<span class="diff_sub"> incorporate</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_42">42+</td><td nowrap="nowrap"> <span class="diff_add"> objects</span> in versions of Python prior to 2.3, you would probably do well to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_43">43-</td><td nowrap="nowrap"> the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed,<span class="diff_sub"> in the source of</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_43">43+</td><td nowrap="nowrap"> <span class="diff_add"> incorporate</span> the source of :cfunc:`PySlice_GetIndicesEx`, suitably renamed,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_44">44-</td><td nowrap="nowrap"><span class="diff_sub"> your extension.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_44">44+</td><td nowrap="nowrap"><span class="diff_add"> in the source of your extension.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_45">45+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to24__4"></td><td class="diff_header" id="to24_46">46+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_47">47+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *length* and an</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_48">48+</td><td nowrap="nowrap"><span class="diff_add"> :ctype:`int *` type for *start*, *stop*, and *step*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_49">49+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from24_45">45</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_46">46</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_47">47</td><td nowrap="nowrap">.. 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)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_48">48</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to24__5">n</a></td><td class="diff_header" id="from24_49">49-</td><td nowrap="nowrap"> Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start,<span class="diff_sub"> stop,</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to24__5">n</a></td><td class="diff_header" id="to24_54">54+</td><td nowrap="nowrap"> Usable replacement for :cfunc:`PySlice_GetIndices`. Retrieve the start,</td></tr> +<tr><td class="diff_next" id="difflib_chg_to24__5"></td><td class="diff_header" id="from24_50">50-</td><td nowrap="nowrap"> and step indices from the slice object *slice* assuming a sequence of<span class="diff_sub"> length</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to24__5"></td><td class="diff_header" id="to24_55">55+</td><td nowrap="nowrap"> <span class="diff_add"> stop,</span> and step indices from the slice object *slice* assuming a sequence of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_51">51-</td><td nowrap="nowrap"> *length*, and store the length of the slice in *slicelength*. Out<span class="diff_sub"> of bounds</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_56">56+</td><td nowrap="nowrap"> <span class="diff_add"> length</span> *length*, and store the length of the slice in *slicelength*. Out</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from24_52">52-</td><td nowrap="nowrap"> indices are clipped in a manner consistent with the handling of<span class="diff_sub"> normal slices.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_57">57+</td><td nowrap="nowrap"> <span class="diff_add"> of bounds</span> indices are clipped in a manner consistent with the handling of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_58">58+</td><td nowrap="nowrap"><span class="diff_add"> normal slices.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from24_53">53</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_54">54</td><td nowrap="nowrap"> Returns 0 on success and -1 on error with exception set.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_55">55</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from24_56">56</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to24__top">t</a></td><td class="diff_header" id="to24_63">63+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_64">64+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_65">65+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *length* and an</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_66">66+</td><td nowrap="nowrap"><span class="diff_add"> :ctype:`int *` type for *start*, *stop*, *step*, and *slicelength*. This</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_67">67+</td><td nowrap="nowrap"><span class="diff_add"> might require changes in your code for properly supporting 64-bit</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to24_68">68+</td><td nowrap="nowrap"><span class="diff_add"> systems.</span></td></tr> + </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/string.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,238 @@ +--- r262/c-api/string.rst 2009-02-02 17:27:16.400413000 +0900 ++++ r266/c-api/string.rst 2009-10-27 22:38:33.383488000 +0900 +@@ -1,25 +1,27 @@ + .. highlightlang:: c + + .. _stringobjects: + + String/Bytes Objects + -------------------- + + These functions raise :exc:`TypeError` when expecting a string parameter and are + called with a non-string parameter. + + .. note:: +- These functions have been renamed to PyBytes_* in Python 3.x. The PyBytes +- names are also available in 2.6. ++ ++ These functions have been renamed to PyBytes_* in Python 3.x. Unless ++ otherwise noted, the PyBytes functions available in 3.x are aliased to their ++ PyString_* equivalents to help porting. + + .. index:: object: string + + + .. ctype:: PyStringObject + + This subtype of :ctype:`PyObject` represents a Python string object. + + + .. cvar:: PyTypeObject PyString_Type + + .. index:: single: StringType (in module types) +@@ -49,24 +51,28 @@ + + Return a new string object with a copy of the string *v* as value on success, + and *NULL* on failure. The parameter *v* must not be *NULL*; it will not be + checked. + + + .. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len) + + Return a new string object with a copy of the string *v* as value and length + *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, ...) + + Take a C :cfunc:`printf`\ -style *format* string and a variable number of + arguments, calculate the size of the resulting Python string and return a string + with the values formatted into it. The variable arguments must be C types and + must correspond exactly to the format characters in the *format* string. The + following format characters are allowed: + + .. % This should be exactly the same as the table in PyErr_Format. + .. % One should just refer to the other. + .. % The descriptions for %zd and %zu are wrong, but the truth is complicated +@@ -123,29 +129,37 @@ + + + .. cfunction:: PyObject* PyString_FromFormatV(const char *format, va_list vargs) + + Identical to :cfunc:`PyString_FromFormat` except that it takes exactly two + arguments. + + + .. cfunction:: Py_ssize_t PyString_Size(PyObject *string) + + 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) + + Return a NUL-terminated representation of the contents of *string*. The pointer + refers to the internal buffer of *string*, not a copy. The data must not be + modified in any way, unless the string was just created using + ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If + *string* is a Unicode object, this function computes the default encoding of + *string* and operates on that. If *string* is not a string object at all, + :cfunc:`PyString_AsString` returns *NULL* and raises :exc:`TypeError`. + + +@@ -163,24 +177,28 @@ + The function accepts both string and Unicode objects as input. For Unicode + objects it returns the default encoded version of the object. If *length* is + *NULL*, the resulting buffer may not contain NUL characters; if it does, the + function returns ``-1`` and a :exc:`TypeError` is raised. + + The buffer refers to an internal string buffer of *obj*, not a copy. The data + must not be modified in any way, unless the string was just created using + ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If + *string* is a Unicode object, this function computes the default encoding of + *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) + + Create a new string object in *\*string* containing the contents of *newpart* + appended to *string*; the caller will own the new reference. The reference to + the old value of *string* will be stolen. If the new string cannot be created, + the old reference to *string* will still be discarded and the value of + *\*string* will be set to *NULL*; the appropriate exception will be set. + + + .. cfunction:: void PyString_ConcatAndDel(PyObject **string, PyObject *newpart) + +@@ -191,74 +209,109 @@ + .. cfunction:: int _PyString_Resize(PyObject **string, Py_ssize_t newsize) + + A way to resize a string object even though it is "immutable". Only use this to + build up a brand new string object; don't use this if the string may already be + known in other parts of the code. It is an error to call this function if the + refcount on the input string object is not one. Pass the address of an existing + string object as an lvalue (it may be written into), and the new size desired. + On success, *\*string* holds the resized string object and ``0`` is returned; + the address in *\*string* may differ from its input value. If the reallocation + 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) + + Return a new string object from *format* and *args*. Analogous to ``format % + args``. The *args* argument must be a tuple. + + + .. cfunction:: void PyString_InternInPlace(PyObject **string) + + Intern the argument *\*string* in place. The argument must be the address of a + pointer variable pointing to a Python string object. If there is an existing + interned string that is the same as *\*string*, it sets *\*string* to it + (decrementing the reference count of the old string object and incrementing the + reference count of the interned string object), otherwise it leaves *\*string* + alone and interns it (incrementing its reference count). (Clarification: even + though there is a lot of talk about reference counts, think of this function as + reference-count-neutral; you own the object after the call if and only if you + owned it before the call.) + ++ .. note:: ++ ++ This function is not available in 3.x and does not have a PyBytes alias. ++ + + .. cfunction:: PyObject* PyString_InternFromString(const char *v) + + A combination of :cfunc:`PyString_FromString` and + :cfunc:`PyString_InternInPlace`, returning either a new string object that has + been interned, or a new ("owned") reference to an earlier interned string object + with the same value. + ++ .. note:: ++ ++ This function is not available in 3.x and does not have a PyBytes alias. ++ + + .. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) + + Create an object by decoding *size* bytes of the encoded buffer *s* using the + codec registered for *encoding*. *encoding* and *errors* have the same meaning + as the parameters of the same name in the :func:`unicode` built-in function. + The codec to be used is looked up using the Python codec registry. Return + *NULL* if an exception was raised by the codec. + ++ .. note:: ++ ++ This function is not available in 3.x and does not have a PyBytes alias. ++ ++ .. 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) + + Decode a string object by passing it to the codec registered for *encoding* and + return the result as Python object. *encoding* and *errors* have the same + meaning as the parameters of the same name in the string :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. + ++ .. note:: ++ ++ This function is not available in 3.x and does not have a PyBytes alias. ++ + + .. cfunction:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors) + + Encode the :ctype:`char` buffer of the given size by passing it to the codec + registered for *encoding* and return a Python object. *encoding* and *errors* + have the same meaning as the parameters of the same name in the string + :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. + ++ .. note:: ++ ++ This function is not available in 3.x and does not have a PyBytes alias. ++ ++ .. 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) + + Encode a string object using the codec registered for *encoding* and return the + result as Python object. *encoding* and *errors* have the same meaning as the + parameters of the same name in the string :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. ++ ++ .. note:: ++ ++ This function is not available in 3.x and does not have a PyBytes alias. ======================================= --- /dev/null +++ /c-api/diff/string.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,115 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to25__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/string.rst => r266/c-api/string.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to25__0"></td><td class="diff_header" id="from25_4">4</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_5">5</td><td nowrap="nowrap">String/Bytes Objects</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_6">6</td><td nowrap="nowrap">--------------------</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_7">7</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_8">8</td><td nowrap="nowrap">These functions raise :exc:`TypeError` when expecting a string parameter and are</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_9">9</td><td nowrap="nowrap">called with a non-string parameter.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_10">10</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_11">11</td><td nowrap="nowrap">.. note::</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__1">n</a></td><td class="diff_header" id="to25_12">12+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from25_12">12-</td><td nowrap="nowrap"> These functions have been renamed to PyBytes_* in Python 3.x. <span class="diff_chg">The PyByt</span>es</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_13">13+</td><td nowrap="nowrap"> These functions have been renamed to PyBytes_* in Python 3.x. <span class="diff_chg">Unl</span>es<span class="diff_add">s</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from25_13">13-</td><td nowrap="nowrap"><span class="diff_sub"> names are also available in 2.6.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_14">14+</td><td nowrap="nowrap"><span class="diff_add"> otherwise noted, the PyBytes functions available in 3.x are aliased to their</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_15">15+</td><td nowrap="nowrap"><span class="diff_add"> PyString_* equivalents to help porting.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_14">14</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_15">15</td><td nowrap="nowrap">.. index:: object: string</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_16">16</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_17">17</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_18">18</td><td nowrap="nowrap">.. ctype:: PyStringObject</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_19">19</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_20">20</td><td nowrap="nowrap"> This subtype of :ctype:`PyObject` represents a Python string object.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_21">21</td><td nowrap="nowrap"></td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to25__1"></td><td class="diff_header" id="from25_52">52</td><td nowrap="nowrap"> checked.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_53">53</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_54">54</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_55">55</td><td nowrap="nowrap">.. cfunction:: PyObject* PyString_FromStringAndSize(const char *v, Py_ssize_t len)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_56">56</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_57">57</td><td nowrap="nowrap"> Return a new string object with a copy of the string *v* as value and length</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_58">58</td><td nowrap="nowrap"> *len* on success, and *NULL* on failure. If *v* is *NULL*, the contents of the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_59">59</td><td nowrap="nowrap"> string are uninitialized.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__2">n</a></td><td class="diff_header" id="to25_62">62+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_63">63+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_64">64+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *len*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_65">65+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_60">60</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_61">61</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_62">62</td><td nowrap="nowrap">.. cfunction:: PyObject* PyString_FromFormat(const char *format, ...)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_63">63</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_64">64</td><td nowrap="nowrap"> Take a C :cfunc:`printf`\ -style *format* string and a variable number of</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_65">65</td><td nowrap="nowrap"> arguments, calculate the size of the resulting Python string and return a string</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_66">66</td><td nowrap="nowrap"> with the values formatted into it. The variable arguments must be C types and</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_67">67</td><td nowrap="nowrap"> must correspond exactly to the format characters in the *format* string. The</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to25__2"></td><td class="diff_header" id="from25_127">127</td><td nowrap="nowrap"> Identical to :cfunc:`PyString_FromFormat` except that it takes exactly two</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_128">128</td><td nowrap="nowrap"> arguments.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_129">129</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_130">130</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_131">131</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PyString_Size(PyObject *string)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_132">132</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_133">133</td><td nowrap="nowrap"> Return the length of the string in string object *string*.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_134">134</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next" id="difflib_chg_to25__3"><a href="#difflib_chg_to25__3">n</a></td><td class="diff_header" id="to25_141">141+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_142">142+</td><td nowrap="nowrap"><span class="diff_add"> This function returned an :ctype:`int` type. This might require changes</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_143">143+</td><td nowrap="nowrap"><span class="diff_add"> in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_144">144+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_135">135</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_136">136</td><td nowrap="nowrap">.. cfunction:: Py_ssize_t PyString_GET_SIZE(PyObject *string)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_137">137</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_138">138</td><td nowrap="nowrap"> Macro form of :cfunc:`PyString_Size` but without error checking.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__4">n</a></td><td class="diff_header" id="to25_149">149+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_150">150+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_151">151+</td><td nowrap="nowrap"><span class="diff_add"> This macro returned an :ctype:`int` type. This might require changes in</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_152">152+</td><td nowrap="nowrap"><span class="diff_add"> your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_139">139</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_140">140</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_141">141</td><td nowrap="nowrap">.. cfunction:: char* PyString_AsString(PyObject *string)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_142">142</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_143">143</td><td nowrap="nowrap"> Return a NUL-terminated representation of the contents of *string*. The pointer</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_144">144</td><td nowrap="nowrap"> refers to the internal buffer of *string*, not a copy. The data must not be</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_145">145</td><td nowrap="nowrap"> modified in any way, unless the string was just created using</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_146">146</td><td nowrap="nowrap"> ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to25__4"></td><td class="diff_header" id="from25_166">166</td><td nowrap="nowrap"> function returns ``-1`` and a :exc:`TypeError` is raised.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_167">167</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_168">168</td><td nowrap="nowrap"> The buffer refers to an internal string buffer of *obj*, not a copy. The data</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_169">169</td><td nowrap="nowrap"> must not be modified in any way, unless the string was just created using</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_170">170</td><td nowrap="nowrap"> ``PyString_FromStringAndSize(NULL, size)``. It must not be deallocated. If</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_171">171</td><td nowrap="nowrap"> *string* is a Unicode object, this function computes the default encoding of</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_172">172</td><td nowrap="nowrap"> *string* and operates on that. If *string* is not a string object at all,</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_173">173</td><td nowrap="nowrap"> :cfunc:`PyString_AsStringAndSize` returns ``-1`` and raises :exc:`TypeError`.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__5">n</a></td><td class="diff_header" id="to25_188">188+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_189">189+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_190">190+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int *` type for *length*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_191">191+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_174">174</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_175">175</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_176">176</td><td nowrap="nowrap">.. cfunction:: void PyString_Concat(PyObject **string, PyObject *newpart)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_177">177</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_178">178</td><td nowrap="nowrap"> Create a new string object in *\*string* containing the contents of *newpart*</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_179">179</td><td nowrap="nowrap"> appended to *string*; the caller will own the new reference. The reference to</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_180">180</td><td nowrap="nowrap"> the old value of *string* will be stolen. If the new string cannot be created,</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_181">181</td><td nowrap="nowrap"> the old reference to *string* will still be discarded and the value of</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to25__5"></td><td class="diff_header" id="from25_195">195</td><td nowrap="nowrap"> known in other parts of the code. It is an error to call this function if the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_196">196</td><td nowrap="nowrap"> refcount on the input string object is not one. Pass the address of an existing</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_197">197</td><td nowrap="nowrap"> string object as an lvalue (it may be written into), and the new size desired.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_198">198</td><td nowrap="nowrap"> On success, *\*string* holds the resized string object and ``0`` is returned;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_199">199</td><td nowrap="nowrap"> the address in *\*string* may differ from its input value. If the reallocation</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_200">200</td><td nowrap="nowrap"> fails, the original string object at *\*string* is deallocated, *\*string* is</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_201">201</td><td nowrap="nowrap"> set to *NULL*, a memory exception is set, and ``-1`` is returned.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_202">202</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__6">n</a></td><td class="diff_header" id="to25_221">221+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_222">222+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *newsize*. This might</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_223">223+</td><td nowrap="nowrap"><span class="diff_add"> require changes in your code for properly supporting 64-bit systems.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_203">203</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_204">204</td><td nowrap="nowrap">.. cfunction:: PyObject* PyString_Format(PyObject *format, PyObject *args)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_205">205</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_206">206</td><td nowrap="nowrap"> Return a new string object from *format* and *args*. Analogous to ``format %</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_207">207</td><td nowrap="nowrap"> args``. The *args* argument must be a tuple.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_208">208</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_209">209</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_210">210</td><td nowrap="nowrap">.. cfunction:: void PyString_InternInPlace(PyObject **string)</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to25__6"></td><td class="diff_header" id="from25_214">214</td><td nowrap="nowrap"> interned string that is the same as *\*string*, it sets *\*string* to it</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_215">215</td><td nowrap="nowrap"> (decrementing the reference count of the old string object and incrementing the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_216">216</td><td nowrap="nowrap"> reference count of the interned string object), otherwise it leaves *\*string*</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_217">217</td><td nowrap="nowrap"> alone and interns it (incrementing its reference count). (Clarification: even</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_218">218</td><td nowrap="nowrap"> though there is a lot of talk about reference counts, think of this function as</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_219">219</td><td nowrap="nowrap"> reference-count-neutral; you own the object after the call if and only if you</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_220">220</td><td nowrap="nowrap"> owned it before the call.)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_221">221</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__7">n</a></td><td class="diff_header" id="to25_243">243+</td><td nowrap="nowrap"><span class="diff_add"> .. note::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_244">244+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_245">245+</td><td nowrap="nowrap"><span class="diff_add"> This function is not available in 3.x and does not have a PyBytes alias.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to25__7"></td><td class="diff_header" id="to25_246">246+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_222">222</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_223">223</td><td nowrap="nowrap">.. cfunction:: PyObject* PyString_InternFromString(const char *v)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_224">224</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_225">225</td><td nowrap="nowrap"> A combination of :cfunc:`PyString_FromString` and</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_226">226</td><td nowrap="nowrap"> :cfunc:`PyString_InternInPlace`, returning either a new string object that has</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_227">227</td><td nowrap="nowrap"> been interned, or a new ("owned") reference to an earlier interned string object</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_228">228</td><td nowrap="nowrap"> with the same value.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__8">n</a></td><td class="diff_header" id="to25_254">254+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_255">255+</td><td nowrap="nowrap"><span class="diff_add"> .. note::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_256">256+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_257">257+</td><td nowrap="nowrap"><span class="diff_add"> This function is not available in 3.x and does not have a PyBytes alias.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_229">229</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_230">230</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to25__8"></td><td class="diff_header" id="from25_231">231</td><td nowrap="nowrap">.. cfunction:: PyObject* PyString_Decode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_232">232</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_233">233</td><td nowrap="nowrap"> Create an object by decoding *size* bytes of the encoded buffer *s* using the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_234">234</td><td nowrap="nowrap"> codec registered for *encoding*. *encoding* and *errors* have the same meaning</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_235">235</td><td nowrap="nowrap"> as the parameters of the same name in the :func:`unicode` built-in function.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_236">236</td><td nowrap="nowrap"> The codec to be used is looked up using the Python codec registry. Return</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_237">237</td><td nowrap="nowrap"> *NULL* if an exception was raised by the codec.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_238">238</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__9">n</a></td><td class="diff_header" id="to25_268">268+</td><td nowrap="nowrap"><span class="diff_add"> .. note::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_269">269+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_270">270+</td><td nowrap="nowrap"><span class="diff_add"> This function is not available in 3.x and does not have a PyBytes alias.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_271">271+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_272">272+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_273">273+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *size*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_274">274+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_275">275+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_239">239</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to25__9"></td><td class="diff_header" id="from25_240">240</td><td nowrap="nowrap">.. cfunction:: PyObject* PyString_AsDecodedObject(PyObject *str, const char *encoding, const char *errors)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_241">241</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_242">242</td><td nowrap="nowrap"> Decode a string object by passing it to the codec registered for *encoding* and</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_243">243</td><td nowrap="nowrap"> return the result as Python object. *encoding* and *errors* have the same</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_244">244</td><td nowrap="nowrap"> meaning as the parameters of the same name in the string :meth:`encode` method.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_245">245</td><td nowrap="nowrap"> The codec to be used is looked up using the Python codec registry. Return *NULL*</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_246">246</td><td nowrap="nowrap"> if an exception was raised by the codec.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_247">247</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__10">n</a></td><td class="diff_header" id="to25_285">285+</td><td nowrap="nowrap"><span class="diff_add"> .. note::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_286">286+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_287">287+</td><td nowrap="nowrap"><span class="diff_add"> This function is not available in 3.x and does not have a PyBytes alias.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_288">288+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from25_248">248</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to25__10"></td><td class="diff_header" id="from25_249">249</td><td nowrap="nowrap">.. cfunction:: PyObject* PyString_Encode(const char *s, Py_ssize_t size, const char *encoding, const char *errors)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_250">250</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_251">251</td><td nowrap="nowrap"> Encode the :ctype:`char` buffer of the given size by passing it to the codec</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_252">252</td><td nowrap="nowrap"> registered for *encoding* and return a Python object. *encoding* and *errors*</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_253">253</td><td nowrap="nowrap"> have the same meaning as the parameters of the same name in the string</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_254">254</td><td nowrap="nowrap"> :meth:`encode` method. The codec to be used is looked up using the Python codec</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_255">255</td><td nowrap="nowrap"> registry. Return *NULL* if an exception was raised by the codec.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_256">256</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__11">n</a></td><td class="diff_header" id="to25_298">298+</td><td nowrap="nowrap"><span class="diff_add"> .. note::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_299">299+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_300">300+</td><td nowrap="nowrap"><span class="diff_add"> This function is not available in 3.x and does not have a PyBytes alias.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_301">301+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_302">302+</td><td nowrap="nowrap"><span class="diff_add"> .. versionchanged:: 2.5</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_303">303+</td><td nowrap="nowrap"><span class="diff_add"> This function used an :ctype:`int` type for *size*. This might require</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_304">304+</td><td nowrap="nowrap"><span class="diff_add"> changes in your code for properly supporting 64-bit systems.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_305">305+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to25__11"></td><td class="diff_header" id="from25_257">257</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_258">258</td><td nowrap="nowrap">.. cfunction:: PyObject* PyString_AsEncodedObject(PyObject *str, const char *encoding, const char *errors)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_259">259</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_260">260</td><td nowrap="nowrap"> Encode a string object using the codec registered for *encoding* and return the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_261">261</td><td nowrap="nowrap"> result as Python object. *encoding* and *errors* have the same meaning as the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_262">262</td><td nowrap="nowrap"> parameters of the same name in the string :meth:`encode` method. The codec to be</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_263">263</td><td nowrap="nowrap"> used is looked up using the Python codec registry. Return *NULL* if an exception</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from25_264">264</td><td nowrap="nowrap"> was raised by the codec.</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to25__top">t</a></td><td class="diff_header" id="to25_314">314+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_315">315+</td><td nowrap="nowrap"><span class="diff_add"> .. note::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_316">316+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to25_317">317+</td><td nowrap="nowrap"><span class="diff_add"> This function is not available in 3.x and does not have a PyBytes alias.</span></td></tr> + </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= --- /dev/null +++ /c-api/diff/structures.rst.diff Sat Mar 19 08:30:15 2011 @@ -0,0 +1,314 @@ +--- r262/c-api/structures.rst 2009-04-06 06:21:05.082173000 +0900 ++++ r266/c-api/structures.rst 2010-01-03 18:11:04.291347000 +0900 +@@ -1,91 +1,110 @@ + .. highlightlang:: c + + .. _common-structs: + + Common Object Structures + ======================== + + There are a large number of structures which are used in the definition of + object types for Python. This section describes these structures and how they + are used. + +-All Python objects ultimately share a small number of fields at the beginning of +-the object's representation in memory. These are represented by the +-:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn, by +-the expansions of some macros also used, whether directly or indirectly, in the +-definition of all other Python objects. ++All Python objects ultimately share a small number of fields at the beginning ++of the object's representation in memory. These are represented by the ++:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn, ++by the expansions of some macros also used, whether directly or indirectly, in ++the definition of all other Python objects. + + + .. ctype:: PyObject + +- All object types are extensions of this type. This is a type which contains the +- information Python needs to treat a pointer to an object as an object. In a +- normal "release" build, it contains only the object's reference count and a +- pointer to the corresponding type object. It corresponds to the fields defined +- by the expansion of the ``PyObject_HEAD`` macro. ++ All object types are extensions of this type. This is a type which ++ contains the information Python needs to treat a pointer to an object as an ++ object. In a normal "release" build, it contains only the object's ++ reference count and a pointer to the corresponding type object. It ++ corresponds to the fields defined by the expansion of the ``PyObject_HEAD`` ++ macro. + + + .. ctype:: PyVarObject + +- This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size` field. +- This is only used for objects that have some notion of *length*. This type does +- not often appear in the Python/C API. It corresponds to the fields defined by +- the expansion of the ``PyObject_VAR_HEAD`` macro. ++ This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size` ++ field. This is only used for objects that have some notion of *length*. ++ This type does not often appear in the Python/C API. It corresponds to the ++ fields defined by the expansion of the ``PyObject_VAR_HEAD`` macro. + + These macros are used in the definition of :ctype:`PyObject` and + :ctype:`PyVarObject`: + + + .. cmacro:: PyObject_HEAD + + This is a macro which expands to the declarations of the fields of the + :ctype:`PyObject` type; it is used when declaring new types which represent +- objects without a varying length. The specific fields it expands to depend on +- the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is not +- defined, and :cmacro:`PyObject_HEAD` expands to:: ++ objects without a varying length. The specific fields it expands to depend ++ on the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is ++ not defined, and :cmacro:`PyObject_HEAD` expands to:: + + Py_ssize_t ob_refcnt; + PyTypeObject *ob_type; + + When :cmacro:`Py_TRACE_REFS` is defined, it expands to:: + + PyObject *_ob_next, *_ob_prev; + Py_ssize_t ob_refcnt; + PyTypeObject *ob_type; + + + .. cmacro:: PyObject_VAR_HEAD + + This is a macro which expands to the declarations of the fields of the +- :ctype:`PyVarObject` type; it is used when declaring new types which represent +- objects with a length that varies from instance to instance. This macro always +- expands to:: ++ :ctype:`PyVarObject` type; it is used when declaring new types which ++ represent objects with a length that varies from instance to instance. ++ This macro always expands to:: + + PyObject_HEAD + Py_ssize_t ob_size; + + Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own + expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`. + +-PyObject_HEAD_INIT ++ ++.. cmacro:: PyObject_HEAD_INIT(type) ++ ++ This is a macro which expands to initialization values for a new ++ :ctype:`PyObject` type. This macro expands to:: ++ ++ _PyObject_EXTRA_INIT ++ 1, type, ++ ++ ++.. cmacro:: PyVarObject_HEAD_INIT(type, size) ++ ++ This is a macro which expands to initialization values for a new ++ :ctype:`PyVarObject` type, including the :attr:`ob_size` field. ++ This macro expands to:: ++ ++ _PyObject_EXTRA_INIT ++ 1, type, size, + + + .. ctype:: PyCFunction + +- Type of the functions used to implement most Python callables in C. Functions of +- this type take two :ctype:`PyObject\*` parameters and return one such value. If +- the return value is *NULL*, an exception shall have been set. If not *NULL*, +- the return value is interpreted as the return value of the function as exposed +- in Python. The function must return a new reference. ++ Type of the functions used to implement most Python callables in C. ++ Functions of this type take two :ctype:`PyObject\*` parameters and return ++ one such value. If the return value is *NULL*, an exception shall have ++ been set. If not *NULL*, the return value is interpreted as the return ++ value of the function as exposed in Python. The function must return a new ++ reference. + + + .. ctype:: PyMethodDef + + Structure used to describe a method of an extension type. This structure has + four fields: + + +------------------+-------------+-------------------------------+ + | Field | C Type | Meaning | + +==================+=============+===============================+ + | :attr:`ml_name` | char \* | name of the method | + +------------------+-------------+-------------------------------+ +@@ -108,108 +127,111 @@ + + The :attr:`ml_flags` field is a bitfield which can include the following flags. + The individual flags indicate either a calling convention or a binding + convention. Of the calling convention flags, only :const:`METH_VARARGS` and + :const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS` + alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling + convention flags can be combined with a binding flag. + + + .. data:: METH_VARARGS + + This is the typical calling convention, where the methods have the type +- :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values. The +- first one is the *self* object for methods; for module functions, it has the +- value given to :cfunc:`Py_InitModule4` (or *NULL* if :cfunc:`Py_InitModule` was +- used). The second parameter (often called *args*) is a tuple object +- representing all arguments. This parameter is typically processed using +- :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`. ++ :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values. ++ The first one is the *self* object for methods; for module functions, it ++ has the value given to :cfunc:`Py_InitModule4` (or *NULL* if ++ :cfunc:`Py_InitModule` was used). The second parameter (often called ++ *args*) is a tuple object representing all arguments. This parameter is ++ typically processed using :cfunc:`PyArg_ParseTuple` or ++ :cfunc:`PyArg_UnpackTuple`. + + + .. data:: METH_KEYWORDS + +- Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`. The +- function expects three parameters: *self*, *args*, and a dictionary of all the +- keyword arguments. The flag is typically combined with :const:`METH_VARARGS`, +- and the parameters are typically processed using ++ Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`. ++ The function expects three parameters: *self*, *args*, and a dictionary of ++ all the keyword arguments. The flag is typically combined with ++ :const:`METH_VARARGS`, and the parameters are typically processed using + :cfunc:`PyArg_ParseTupleAndKeywords`. + + + .. data:: METH_NOARGS + + Methods without parameters don't need to check whether arguments are given if + they are listed with the :const:`METH_NOARGS` flag. They need to be of type + :ctype:`PyCFunction`. When used with object methods, the first parameter is +- typically named ``self`` and will hold a reference to the object instance. In +- all cases the second parameter will be *NULL*. ++ typically named ``self`` and will hold a reference to the object instance. ++ In all cases the second parameter will be *NULL*. + + + .. data:: METH_O + + Methods with a single object argument can be listed with the :const:`METH_O` + flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument. + They have the type :ctype:`PyCFunction`, with the *self* parameter, and a + :ctype:`PyObject\*` parameter representing the single argument. + + + .. data:: METH_OLDARGS + + This calling convention is deprecated. The method must be of type +- :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are given, +- a single object if exactly one argument is given, and a tuple of objects if more +- than one argument is given. There is no way for a function using this +- convention to distinguish between a call with multiple arguments and a call with +- a tuple as the only argument. ++ :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are ++ given, a single object if exactly one argument is given, and a tuple of ++ objects if more than one argument is given. There is no way for a function ++ using this convention to distinguish between a call with multiple arguments ++ and a call with a tuple as the only argument. + + These two constants are not used to indicate the calling convention but the + binding when use with methods of classes. These may not be used for functions + defined for modules. At most one of these flags may be set for any given + method. + + + .. data:: METH_CLASS + + .. index:: builtin: classmethod + +- The method will be passed the type object as the first parameter rather than an +- instance of the type. This is used to create *class methods*, similar to what +- is created when using the :func:`classmethod` built-in function. ++ The method will be passed the type object as the first parameter rather ++ than an instance of the type. This is used to create *class methods*, ++ similar to what is created when using the :func:`classmethod` built-in ++ function. + + .. versionadded:: 2.3 + + + .. data:: METH_STATIC + + .. index:: builtin: staticmethod + +- The method will be passed *NULL* as the first parameter rather than an instance +- of the type. This is used to create *static methods*, similar to what is +- created when using the :func:`staticmethod` built-in function. ++ The method will be passed *NULL* as the first parameter rather than an ++ instance of the type. This is used to create *static methods*, similar to ++ what is created when using the :func:`staticmethod` built-in function. + + .. versionadded:: 2.3 + + One other constant controls whether a method is loaded in place of another + definition with the same method name. + + + .. data:: METH_COEXIST + + The method will be loaded in place of existing definitions. Without + *METH_COEXIST*, the default is to skip repeated definitions. Since slot +- wrappers are loaded before the method table, the existence of a *sq_contains* +- slot, for example, would generate a wrapped method named :meth:`__contains__` +- and preclude the loading of a corresponding PyCFunction with the same name. +- With the flag defined, the PyCFunction will be loaded in place of the wrapper +- object and will co-exist with the slot. This is helpful because calls to +- PyCFunctions are optimized more than wrapper object calls. ++ wrappers are loaded before the method table, the existence of a ++ *sq_contains* slot, for example, would generate a wrapped method named ++ :meth:`__contains__` and preclude the loading of a corresponding ++ PyCFunction with the same name. With the flag defined, the PyCFunction ++ will be loaded in place of the wrapper object and will co-exist with the ++ slot. This is helpful because calls to PyCFunctions are optimized more ++ than wrapper object calls. + + .. versionadded:: 2.4 + + + .. ctype:: PyMemberDef + + Structure which describes an attribute of a type which corresponds to a C + struct member. Its fields are: + + +------------------+-------------+-------------------------------+ + | Field | C Type | Meaning | + +==================+=============+===============================+ +@@ -250,25 +272,29 @@ + T_UBYTE unsigned char + T_UINT unsigned int + T_USHORT unsigned short + T_ULONG unsigned long + T_BOOL char + T_LONGLONG long long + T_ULONGLONG unsigned long long + T_PYSSIZET Py_ssize_t + =============== ================== + + :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` differ in that + :cmacro:`T_OBJECT` returns ``None`` if the member is *NULL* and +- :cmacro:`T_OBJECT_EX` raises an :exc:`AttributeError`. ++ :cmacro:`T_OBJECT_EX` raises an :exc:`AttributeError`. Try to use ++ :cmacro:`T_OBJECT_EX` over :cmacro:`T_OBJECT` because :cmacro:`T_OBJECT_EX` ++ handles use of the :keyword:`del` statement on that attribute more correctly ++ than :cmacro:`T_OBJECT`. + + :attr:`flags` can be 0 for write and read access or :cmacro:`READONLY` for + read-only access. Using :cmacro:`T_STRING` for :attr:`type` implies + :cmacro:`READONLY`. Only :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` + members can be deleted. (They are set to *NULL*). + + + .. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name) + +- Return a bound method object for an extension type implemented in C. This can +- be useful in the implementation of a :attr:`tp_getattro` or :attr:`tp_getattr` +- handler that does not use the :cfunc:`PyObject_GenericGetAttr` function. ++ Return a bound method object for an extension type implemented in C. This ++ can be useful in the implementation of a :attr:`tp_getattro` or ++ :attr:`tp_getattr` handler that does not use the ++ :cfunc:`PyObject_GenericGetAttr` function. ======================================= --- /dev/null +++ /c-api/diff/structures.rst.html Sat Mar 19 08:30:15 2011 @@ -0,0 +1,196 @@ + +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html> + +<head> + <meta http-equiv="Content-Type" + content="text/html; charset=ISO-8859-1" /> + <title></title> + <style type="text/css"> + table.diff {font-family:Courier; border:medium;} + .diff_header {background-color:#e0e0e0} + td.diff_header {text-align:right} + .diff_next {background-color:#c0c0c0} + .diff_add {background-color:#aaffaa} + .diff_chg {background-color:#ffff77} + .diff_sub {background-color:#ffaaaa} + </style> +</head> + +<body> + + <table class="diff" id="difflib_chg_to26__top" + cellspacing="0" cellpadding="0" rules="groups" > + <colgroup></colgroup> <colgroup></colgroup> <colgroup></colgroup> + <thead><tr><th class="diff_next"><br /></th><th colspan="2" class="diff_header">r262/c-api/structures.rst => r266/c-api/structures.rst</th></tr></thead> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to26__0"></td><td class="diff_header" id="from26_4">4</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_5">5</td><td nowrap="nowrap">Common Object Structures</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_6">6</td><td nowrap="nowrap">========================</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_7">7</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_8">8</td><td nowrap="nowrap">There are a large number of structures which are used in the definition of</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_9">9</td><td nowrap="nowrap">object types for Python. This section describes these structures and how they</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_10">10</td><td nowrap="nowrap">are used.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_11">11</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__1">n</a></td><td class="diff_header" id="from26_12">12-</td><td nowrap="nowrap">All Python objects ultimately share a small number of fields at the beginning<span class="diff_sub"> of</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__1">n</a></td><td class="diff_header" id="to26_12">12+</td><td nowrap="nowrap">All Python objects ultimately share a small number of fields at the beginning</td></tr> +<tr><td class="diff_next" id="difflib_chg_to26__1"></td><td class="diff_header" id="from26_13">13-</td><td nowrap="nowrap">the object's representation in memory. These are represented by the</td></tr> +<tr><td class="diff_next" id="difflib_chg_to26__1"></td><td class="diff_header" id="to26_13">13+</td><td nowrap="nowrap"><span class="diff_add">of </span>the object's representation in memory. These are represented by the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_14">14-</td><td nowrap="nowrap">:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn,<span class="diff_sub"> by</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_14">14+</td><td nowrap="nowrap">:ctype:`PyObject` and :ctype:`PyVarObject` types, which are defined, in turn,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_15">15-</td><td nowrap="nowrap">the expansions of some macros also used, whether directly or indirectly, in<span class="diff_sub"> the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_15">15+</td><td nowrap="nowrap"><span class="diff_add">by </span>the expansions of some macros also used, whether directly or indirectly, in</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_16">16-</td><td nowrap="nowrap">definition of all other Python objects.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_16">16+</td><td nowrap="nowrap"><span class="diff_add">the </span>definition of all other Python objects.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_17">17</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_18">18</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_19">19</td><td nowrap="nowrap">.. ctype:: PyObject</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_20">20</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__2">n</a></td><td class="diff_header" id="from26_21">21-</td><td nowrap="nowrap"> All object types are extensions of this type. This is a type which<span class="diff_sub"> contains the</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__2">n</a></td><td class="diff_header" id="to26_21">21+</td><td nowrap="nowrap"> All object types are extensions of this type. This is a type which</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_22">22-</td><td nowrap="nowrap"> information Python needs to treat a pointer to an object as an<span class="diff_sub"> object. In a</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_22">22+</td><td nowrap="nowrap"> <span class="diff_add"> contains the</span> information Python needs to treat a pointer to an object as an</td></tr> +<tr><td class="diff_next" id="difflib_chg_to26__2"></td><td class="diff_header" id="from26_23">23-</td><td nowrap="nowrap"> normal "release" build, it contains only the object's<span class="diff_sub"> reference count and a</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to26__2"></td><td class="diff_header" id="to26_23">23+</td><td nowrap="nowrap"> <span class="diff_add"> object. In a</span> normal "release" build, it contains only the object's</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_24">24-</td><td nowrap="nowrap"><span class="diff_sub"> pointer to the corresponding type object. It corresponds to the fields defined</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_24">24+</td><td nowrap="nowrap"><span class="diff_add"> reference count and a pointer to the corresponding type object. It</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_25">25-</td><td nowrap="nowrap"><span class="diff_sub"> by the expansion of the ``PyObject_HEAD`` macro.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_25">25+</td><td nowrap="nowrap"><span class="diff_add"> corresponds to the fields defined by the expansion of the ``PyObject_HEAD``</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_26">26+</td><td nowrap="nowrap"><span class="diff_add"> macro.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_26">26</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_27">27</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_28">28</td><td nowrap="nowrap">.. ctype:: PyVarObject</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_29">29</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__3">n</a></td><td class="diff_header" id="from26_30">30-</td><td nowrap="nowrap"> This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size`<span class="diff_sub"> field.</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__3">n</a></td><td class="diff_header" id="to26_31">31+</td><td nowrap="nowrap"> This is an extension of :ctype:`PyObject` that adds the :attr:`ob_size`</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_31">31-</td><td nowrap="nowrap"> This is only used for objects that have some notion of *length*.<span class="diff_sub"> This type does</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_32">32+</td><td nowrap="nowrap"> <span class="diff_add"> field.</span> This is only used for objects that have some notion of *length*.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_32">32-</td><td nowrap="nowrap"> not often appear in the Python/C API. It corresponds to the<span class="diff_sub"> fields defined by</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_33">33+</td><td nowrap="nowrap"> <span class="diff_add"> This type does</span> not often appear in the Python/C API. It corresponds to the</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_33">33-</td><td nowrap="nowrap"> the expansion of the ``PyObject_VAR_HEAD`` macro.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_34">34+</td><td nowrap="nowrap"> <span class="diff_add"> fields defined by</span> the expansion of the ``PyObject_VAR_HEAD`` macro.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_34">34</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to26__3"></td><td class="diff_header" id="from26_35">35</td><td nowrap="nowrap">These macros are used in the definition of :ctype:`PyObject` and</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_36">36</td><td nowrap="nowrap">:ctype:`PyVarObject`:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_37">37</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_38">38</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_39">39</td><td nowrap="nowrap">.. cmacro:: PyObject_HEAD</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_40">40</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_41">41</td><td nowrap="nowrap"> This is a macro which expands to the declarations of the fields of the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_42">42</td><td nowrap="nowrap"> :ctype:`PyObject` type; it is used when declaring new types which represent</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__4">n</a></td><td class="diff_header" id="from26_43">43-</td><td nowrap="nowrap"> objects without a varying length. The specific fields it expands to depend<span class="diff_sub"> on</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__4">n</a></td><td class="diff_header" id="to26_44">44+</td><td nowrap="nowrap"> objects without a varying length. The specific fields it expands to depend</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_44">44-</td><td nowrap="nowrap"> the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is<span class="diff_sub"> not</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_45">45+</td><td nowrap="nowrap"> <span class="diff_add"> on</span> the definition of :cmacro:`Py_TRACE_REFS`. By default, that macro is</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_45">45-</td><td nowrap="nowrap"> defined, and :cmacro:`PyObject_HEAD` expands to::</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_46">46+</td><td nowrap="nowrap"> <span class="diff_add"> not</span> defined, and :cmacro:`PyObject_HEAD` expands to::</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_46">46</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_47">47</td><td nowrap="nowrap"> Py_ssize_t ob_refcnt;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_48">48</td><td nowrap="nowrap"> PyTypeObject *ob_type;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_49">49</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_50">50</td><td nowrap="nowrap"> When :cmacro:`Py_TRACE_REFS` is defined, it expands to::</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_51">51</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to26__4"></td><td class="diff_header" id="from26_52">52</td><td nowrap="nowrap"> PyObject *_ob_next, *_ob_prev;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_53">53</td><td nowrap="nowrap"> Py_ssize_t ob_refcnt;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_54">54</td><td nowrap="nowrap"> PyTypeObject *ob_type;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_55">55</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_56">56</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_57">57</td><td nowrap="nowrap">.. cmacro:: PyObject_VAR_HEAD</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_58">58</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_59">59</td><td nowrap="nowrap"> This is a macro which expands to the declarations of the fields of the</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__5">n</a></td><td class="diff_header" id="from26_60">60-</td><td nowrap="nowrap"> :ctype:`PyVarObject` type; it is used when declaring new types which<span class="diff_sub"> represent</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__5">n</a></td><td class="diff_header" id="to26_61">61+</td><td nowrap="nowrap"> :ctype:`PyVarObject` type; it is used when declaring new types which</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_61">61-</td><td nowrap="nowrap"> objects with a length that varies from instance to instance.<span class="diff_sub"> This macro always</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_62">62+</td><td nowrap="nowrap"> <span class="diff_add"> represent</span> objects with a length that varies from instance to instance.</td></tr> +<tr><td class="diff_next" id="difflib_chg_to26__5"></td><td class="diff_header" id="from26_62">62-</td><td nowrap="nowrap"><span class="diff_sub"> expands to::</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to26__5"></td><td class="diff_header" id="to26_63">63+</td><td nowrap="nowrap"><span class="diff_add"> This macro always expands to::</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_63">63</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_64">64</td><td nowrap="nowrap"> PyObject_HEAD</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_65">65</td><td nowrap="nowrap"> Py_ssize_t ob_size;</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_66">66</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_67">67</td><td nowrap="nowrap"> Note that :cmacro:`PyObject_HEAD` is part of the expansion, and that its own</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_68">68</td><td nowrap="nowrap"> expansion varies depending on the definition of :cmacro:`Py_TRACE_REFS`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_69">69</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__6">n</a></td><td class="diff_header" id="from26_70">70-</td><td nowrap="nowrap"><span class="diff_sub">PyObject_HEAD_INIT</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__6">n</a></td><td class="diff_header" id="to26_71">71+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_72">72+</td><td nowrap="nowrap"><span class="diff_add">.. cmacro:: PyObject_HEAD_INIT(type)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_73">73+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_74">74+</td><td nowrap="nowrap"><span class="diff_add"> This is a macro which expands to initialization values for a new</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_75">75+</td><td nowrap="nowrap"><span class="diff_add"> :ctype:`PyObject` type. This macro expands to::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_76">76+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_77">77+</td><td nowrap="nowrap"><span class="diff_add"> _PyObject_EXTRA_INIT</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_78">78+</td><td nowrap="nowrap"><span class="diff_add"> 1, type,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_79">79+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_80">80+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_81">81+</td><td nowrap="nowrap"><span class="diff_add">.. cmacro:: PyVarObject_HEAD_INIT(type, size)</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_82">82+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_83">83+</td><td nowrap="nowrap"><span class="diff_add"> This is a macro which expands to initialization values for a new</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_84">84+</td><td nowrap="nowrap"><span class="diff_add"> :ctype:`PyVarObject` type, including the :attr:`ob_size` field.</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to26__6"></td><td class="diff_header" id="to26_85">85+</td><td nowrap="nowrap"><span class="diff_add"> This macro expands to::</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_86">86+</td><td nowrap="nowrap"><span class="diff_add"> </span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_87">87+</td><td nowrap="nowrap"><span class="diff_add"> _PyObject_EXTRA_INIT</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_88">88+</td><td nowrap="nowrap"><span class="diff_add"> 1, type, size,</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_71">71</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_72">72</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_73">73</td><td nowrap="nowrap">.. ctype:: PyCFunction</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_74">74</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__7">n</a></td><td class="diff_header" id="from26_75">75-</td><td nowrap="nowrap"> Type of the functions used to implement most Python callables in C.<span class="diff_sub"> Functions of</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__7">n</a></td><td class="diff_header" id="to26_93">93+</td><td nowrap="nowrap"> Type of the functions used to implement most Python callables in C.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_76">76-</td><td nowrap="nowrap"> this type take two :ctype:`PyObject\*` parameters and return<span class="diff_sub"> one such value. If</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_94">94+</td><td nowrap="nowrap"> <span class="diff_add"> Functions of</span> this type take two :ctype:`PyObject\*` parameters and return</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_77">77-</td><td nowrap="nowrap"><span class="diff_sub"> the return value is *NULL*, an exception shall have been set. If not *NULL*,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_95">95+</td><td nowrap="nowrap"><span class="diff_add"> one such value. If the return value is *NULL*, an exception shall have</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_78">78-</td><td nowrap="nowrap"><span class="diff_sub"> the return value is interpreted as the return value of the function as exposed</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_96">96+</td><td nowrap="nowrap"><span class="diff_add"> been set. If not *NULL*, the return value is interpreted as the return</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_79">79-</td><td nowrap="nowrap"><span class="diff_sub"> in Python. The function must return a new reference.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_97">97+</td><td nowrap="nowrap"><span class="diff_add"> value of the function as exposed in Python. The function must return a new</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_98">98+</td><td nowrap="nowrap"><span class="diff_add"> reference.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_80">80</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_81">81</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_82">82</td><td nowrap="nowrap">.. ctype:: PyMethodDef</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_83">83</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_84">84</td><td nowrap="nowrap"> Structure used to describe a method of an extension type. This structure has</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_85">85</td><td nowrap="nowrap"> four fields:</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_86">86</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_87">87</td><td nowrap="nowrap"> +------------------+-------------+-------------------------------+</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to26__7"></td><td class="diff_header" id="from26_112">112</td><td nowrap="nowrap">:const:`METH_KEYWORDS` can be combined (but note that :const:`METH_KEYWORDS`</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_113">113</td><td nowrap="nowrap">alone is equivalent to ``METH_VARARGS | METH_KEYWORDS``). Any of the calling</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_114">114</td><td nowrap="nowrap">convention flags can be combined with a binding flag.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_115">115</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_116">116</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_117">117</td><td nowrap="nowrap">.. data:: METH_VARARGS</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_118">118</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_119">119</td><td nowrap="nowrap"> This is the typical calling convention, where the methods have the type</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__8">n</a></td><td class="diff_header" id="from26_120">120-</td><td nowrap="nowrap"> :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values.<span class="diff_sub"> The</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__8">n</a></td><td class="diff_header" id="to26_139">139+</td><td nowrap="nowrap"> :ctype:`PyCFunction`. The function expects two :ctype:`PyObject\*` values.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_121">121-</td><td nowrap="nowrap"> first one is the *self* object for methods; for module functions, it<span class="diff_sub"> has the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_140">140+</td><td nowrap="nowrap"> <span class="diff_add"> The</span> first one is the *self* object for methods; for module functions, it</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_122">122-</td><td nowrap="nowrap"> value given to :cfunc:`Py_InitModule4` (or *NULL* if<span class="diff_sub"> :cfunc:`Py_InitModule` was</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_141">141+</td><td nowrap="nowrap"> <span class="diff_add"> has the</span> value given to :cfunc:`Py_InitModule4` (or *NULL* if</td></tr> +<tr><td class="diff_next" id="difflib_chg_to26__8"></td><td class="diff_header" id="from26_123">123-</td><td nowrap="nowrap"><span class="diff_sub"> used). The second parameter (often called *args*) is a tuple object</span></td></tr> +<tr><td class="diff_next" id="difflib_chg_to26__8"></td><td class="diff_header" id="to26_142">142+</td><td nowrap="nowrap"><span class="diff_add"> :cfunc:`Py_InitModule` was used). The second parameter (often called</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_124">124-</td><td nowrap="nowrap"><span class="diff_sub"> representing all arguments. This parameter is typically processed using</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_143">143+</td><td nowrap="nowrap"><span class="diff_add"> *args*) is a tuple object representing all arguments. This parameter is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_125">125-</td><td nowrap="nowrap"><span class="diff_sub"> :cfunc:`PyArg_ParseTuple` or :cfunc:`PyArg_UnpackTuple`.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_144">144+</td><td nowrap="nowrap"><span class="diff_add"> typically processed using :cfunc:`PyArg_ParseTuple` or</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_145">145+</td><td nowrap="nowrap"><span class="diff_add"> :cfunc:`PyArg_UnpackTuple`.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_126">126</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_127">127</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_128">128</td><td nowrap="nowrap">.. data:: METH_KEYWORDS</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_129">129</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__9">n</a></td><td class="diff_header" id="from26_130">130-</td><td nowrap="nowrap"> Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`.<span class="diff_sub"> The</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__9">n</a></td><td class="diff_header" id="to26_150">150+</td><td nowrap="nowrap"> Methods with these flags must be of type :ctype:`PyCFunctionWithKeywords`.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_131">131-</td><td nowrap="nowrap"> function expects three parameters: *self*, *args*, and a dictionary of<span class="diff_sub"> all the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_151">151+</td><td nowrap="nowrap"> <span class="diff_add"> The</span> function expects three parameters: *self*, *args*, and a dictionary of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_132">132-</td><td nowrap="nowrap"> keyword arguments. The flag is typically combined with<span class="diff_sub"> :const:`METH_VARARGS`,</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_152">152+</td><td nowrap="nowrap"> <span class="diff_add"> all the</span> keyword arguments. The flag is typically combined with</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_133">133-</td><td nowrap="nowrap"> and the parameters are typically processed using</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_153">153+</td><td nowrap="nowrap"> <span class="diff_add"> :const:`METH_VARARGS`,</span> and the parameters are typically processed using</td></tr> + <tr><td class="diff_next" id="difflib_chg_to26__9"></td><td class="diff_header" id="from26_134">134</td><td nowrap="nowrap"> :cfunc:`PyArg_ParseTupleAndKeywords`.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_135">135</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_136">136</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_137">137</td><td nowrap="nowrap">.. data:: METH_NOARGS</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_138">138</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_139">139</td><td nowrap="nowrap"> Methods without parameters don't need to check whether arguments are given if</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_140">140</td><td nowrap="nowrap"> they are listed with the :const:`METH_NOARGS` flag. They need to be of type</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_141">141</td><td nowrap="nowrap"> :ctype:`PyCFunction`. When used with object methods, the first parameter is</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__10">n</a></td><td class="diff_header" id="from26_142">142-</td><td nowrap="nowrap"> typically named ``self`` and will hold a reference to the object instance.<span class="diff_sub"> In</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__10">n</a></td><td class="diff_header" id="to26_162">162+</td><td nowrap="nowrap"> typically named ``self`` and will hold a reference to the object instance.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_143">143-</td><td nowrap="nowrap"> all cases the second parameter will be *NULL*.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_163">163+</td><td nowrap="nowrap"> <span class="diff_add"> In</span> all cases the second parameter will be *NULL*.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_144">144</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_145">145</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_146">146</td><td nowrap="nowrap">.. data:: METH_O</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_147">147</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_148">148</td><td nowrap="nowrap"> Methods with a single object argument can be listed with the :const:`METH_O`</td></tr> <tr><td class="diff_next" id="difflib_chg_to26__10"></td><td class="diff_header" id="from26_149">149</td><td nowrap="nowrap"> flag, instead of invoking :cfunc:`PyArg_ParseTuple` with a ``"O"`` argument.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_150">150</td><td nowrap="nowrap"> They have the type :ctype:`PyCFunction`, with the *self* parameter, and a</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_151">151</td><td nowrap="nowrap"> :ctype:`PyObject\*` parameter representing the single argument.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_152">152</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_153">153</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_154">154</td><td nowrap="nowrap">.. data:: METH_OLDARGS</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_155">155</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_156">156</td><td nowrap="nowrap"> This calling convention is deprecated. The method must be of type</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__11">n</a></td><td class="diff_header" id="from26_157">157-</td><td nowrap="nowrap"> :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are<span class="diff_sub"> given,</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__11">n</a></td><td class="diff_header" id="to26_177">177+</td><td nowrap="nowrap"> :ctype:`PyCFunction`. The second argument is *NULL* if no arguments are</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_158">158-</td><td nowrap="nowrap"> a single object if exactly one argument is given, and a tuple of<span class="diff_sub"> objects if more</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_178">178+</td><td nowrap="nowrap"> <span class="diff_add"> given,</span> a single object if exactly one argument is given, and a tuple of</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_159">159-</td><td nowrap="nowrap"> than one argument is given. There is no way for a function<span class="diff_sub"> using this</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_179">179+</td><td nowrap="nowrap"> <span class="diff_add"> objects if more</span> than one argument is given. There is no way for a function</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_160">160-</td><td nowrap="nowrap"> convention to distinguish between a call with multiple arguments<span class="diff_sub"> and a call with</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_180">180+</td><td nowrap="nowrap"> <span class="diff_add"> using this</span> convention to distinguish between a call with multiple arguments</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_161">161-</td><td nowrap="nowrap"> a tuple as the only argument.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_181">181+</td><td nowrap="nowrap"> a<span class="diff_add">nd a call with a</span> tuple as the only argument.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_162">162</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_163">163</td><td nowrap="nowrap">These two constants are not used to indicate the calling convention but the</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_164">164</td><td nowrap="nowrap">binding when use with methods of classes. These may not be used for functions</td></tr> <tr><td class="diff_next" id="difflib_chg_to26__11"></td><td class="diff_header" id="from26_165">165</td><td nowrap="nowrap">defined for modules. At most one of these flags may be set for any given</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_166">166</td><td nowrap="nowrap">method.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_167">167</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_168">168</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_169">169</td><td nowrap="nowrap">.. data:: METH_CLASS</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_170">170</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_171">171</td><td nowrap="nowrap"> .. index:: builtin: classmethod</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_172">172</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__12">n</a></td><td class="diff_header" id="from26_173">173-</td><td nowrap="nowrap"> The method will be passed the type object as the first parameter rather<span class="diff_sub"> than an</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__12">n</a></td><td class="diff_header" id="to26_193">193+</td><td nowrap="nowrap"> The method will be passed the type object as the first parameter rather</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_174">174-</td><td nowrap="nowrap"> instance of the type. This is used to create *class methods*,<span class="diff_sub"> similar to what</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_194">194+</td><td nowrap="nowrap"> <span class="diff_add"> than an</span> instance of the type. This is used to create *class methods*,</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_175">175-</td><td nowrap="nowrap"> is created when using the :func:`classmethod` built-in<span class="diff_sub"> function.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_195">195+</td><td nowrap="nowrap"> <span class="diff_add"> similar to what</span> is created when using the :func:`classmethod` built-in</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_196">196+</td><td nowrap="nowrap"><span class="diff_add"> function.</span></td></tr> + <tr><td class="diff_next" id="difflib_chg_to26__12"></td><td class="diff_header" id="from26_176">176</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_177">177</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_178">178</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_179">179</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_180">180</td><td nowrap="nowrap">.. data:: METH_STATIC</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_181">181</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_182">182</td><td nowrap="nowrap"> .. index:: builtin: staticmethod</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_183">183</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__13">n</a></td><td class="diff_header" id="from26_184">184-</td><td nowrap="nowrap"> The method will be passed *NULL* as the first parameter rather than an<span class="diff_sub"> instance</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__13">n</a></td><td class="diff_header" id="to26_205">205+</td><td nowrap="nowrap"> The method will be passed *NULL* as the first parameter rather than an</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_185">185-</td><td nowrap="nowrap"> of the type. This is used to create *static methods*, similar to<span class="diff_sub"> what is</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_206">206+</td><td nowrap="nowrap"> <span class="diff_add"> instance</span> of the type. This is used to create *static methods*, similar to</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_186">186-</td><td nowrap="nowrap"> created when using the :func:`staticmethod` built-in function.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_207">207+</td><td nowrap="nowrap"> <span class="diff_add"> what is</span> created when using the :func:`staticmethod` built-in function.</td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_187">187</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_188">188</td><td nowrap="nowrap"> .. versionadded:: 2.3</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_189">189</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to26__13"></td><td class="diff_header" id="from26_190">190</td><td nowrap="nowrap">One other constant controls whether a method is loaded in place of another</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_191">191</td><td nowrap="nowrap">definition with the same method name.</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_192">192</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_193">193</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_194">194</td><td nowrap="nowrap">.. data:: METH_COEXIST</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_195">195</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_196">196</td><td nowrap="nowrap"> The method will be loaded in place of existing definitions. Without</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_197">197</td><td nowrap="nowrap"> *METH_COEXIST*, the default is to skip repeated definitions. Since slot</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__14">n</a></td><td class="diff_header" id="from26_198">198-</td><td nowrap="nowrap"> wrappers are loaded before the method table, the existence of a<span class="diff_sub"> *sq_contains*</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__14">n</a></td><td class="diff_header" id="to26_219">219+</td><td nowrap="nowrap"> wrappers are loaded before the method table, the existence of a</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_199">199-</td><td nowrap="nowrap"><span class="diff_sub"> slot, for example, would generate a wrapped method named :meth:`__contains__`</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_220">220+</td><td nowrap="nowrap"><span class="diff_add"> *sq_contains* slot, for example, would generate a wrapped method named</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_200">200-</td><td nowrap="nowrap"><span class="diff_sub"> and preclude the loading of a corresponding PyCFunction with the same name.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_221">221+</td><td nowrap="nowrap"><span class="diff_add"> :meth:`__contains__` and preclude the loading of a corresponding</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_201">201-</td><td nowrap="nowrap"><span class="diff_sub"> With the flag defined, the PyCFunction will be loaded in place of the wrapper</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_222">222+</td><td nowrap="nowrap"><span class="diff_add"> PyCFunction with the same name. With the flag defined, the PyCFunction</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_202">202-</td><td nowrap="nowrap"><span class="diff_sub"> object and will co-exist with the slot. This is helpful because calls to</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_223">223+</td><td nowrap="nowrap"><span class="diff_add"> will be loaded in place of the wrapper object and will co-exist with the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_203">203-</td><td nowrap="nowrap"><span class="diff_sub"> PyCFunctions are optimized more than wrapper object calls.</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_224">224+</td><td nowrap="nowrap"><span class="diff_add"> slot. This is helpful because calls to PyCFunctions are optimized more</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_225">225+</td><td nowrap="nowrap"><span class="diff_add"> than wrapper object calls.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_204">204</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_205">205</td><td nowrap="nowrap"> .. versionadded:: 2.4</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_206">206</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_207">207</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_208">208</td><td nowrap="nowrap">.. ctype:: PyMemberDef</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_209">209</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_210">210</td><td nowrap="nowrap"> Structure which describes an attribute of a type which corresponds to a C</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_211">211</td><td nowrap="nowrap"> struct member. Its fields are:</td></tr> </tbody> + <tbody> + <tr><td class="diff_next" id="difflib_chg_to26__14"></td><td class="diff_header" id="from26_254">254</td><td nowrap="nowrap"> T_BOOL char</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_255">255</td><td nowrap="nowrap"> T_LONGLONG long long</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_256">256</td><td nowrap="nowrap"> T_ULONGLONG unsigned long long</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_257">257</td><td nowrap="nowrap"> T_PYSSIZET Py_ssize_t</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_258">258</td><td nowrap="nowrap"> =============== ==================</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_259">259</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_260">260</td><td nowrap="nowrap"> :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX` differ in that</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_261">261</td><td nowrap="nowrap"> :cmacro:`T_OBJECT` returns ``None`` if the member is *NULL* and</td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__15">n</a></td><td class="diff_header" id="from26_262">262-</td><td nowrap="nowrap"> :cmacro:`T_OBJECT_EX` raises an :exc:`AttributeError`.</td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__15">n</a></td><td class="diff_header" id="to26_284">284+</td><td nowrap="nowrap"> :cmacro:`T_OBJECT_EX` raises an :exc:`AttributeError`.<span class="diff_add"> Try to use</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_285">285+</td><td nowrap="nowrap"><span class="diff_add"> :cmacro:`T_OBJECT_EX` over :cmacro:`T_OBJECT` because :cmacro:`T_OBJECT_EX`</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_286">286+</td><td nowrap="nowrap"><span class="diff_add"> handles use of the :keyword:`del` statement on that attribute more correctly</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_287">287+</td><td nowrap="nowrap"><span class="diff_add"> than :cmacro:`T_OBJECT`.</span></td></tr> + <tr><td class="diff_next"></td><td class="diff_header" id="from26_263">263</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next" id="difflib_chg_to26__15"></td><td class="diff_header" id="from26_264">264</td><td nowrap="nowrap"> :attr:`flags` can be 0 for write and read access or :cmacro:`READONLY` for</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_265">265</td><td nowrap="nowrap"> read-only access. Using :cmacro:`T_STRING` for :attr:`type` implies</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_266">266</td><td nowrap="nowrap"> :cmacro:`READONLY`. Only :cmacro:`T_OBJECT` and :cmacro:`T_OBJECT_EX`</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_267">267</td><td nowrap="nowrap"> members can be deleted. (They are set to *NULL*).</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_268">268</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_269">269</td><td nowrap="nowrap"></td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_270">270</td><td nowrap="nowrap">.. cfunction:: PyObject* Py_FindMethod(PyMethodDef table[], PyObject *ob, char *name)</td></tr> <tr><td class="diff_next"></td><td class="diff_header" id="from26_271">271</td><td nowrap="nowrap"></td></tr><tr><td class="diff_next"><a href="#difflib_chg_to26__top">t</a></td><td class="diff_header" id="from26_272">272-</td><td nowrap="nowrap"> Return a bound method object for an extension type implemented in C. This<span class="diff_sub"> can</span></td></tr> +<tr><td class="diff_next"><a href="#difflib_chg_to26__top">t</a></td><td class="diff_header" id="to26_297">297+</td><td nowrap="nowrap"> Return a bound method object for an extension type implemented in C. This</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_273">273-</td><td nowrap="nowrap"> be useful in the implementation of a :attr:`tp_getattro` or<span class="diff_sub"> :attr:`tp_getattr`</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_298">298+</td><td nowrap="nowrap"> <span class="diff_add"> can</span> be useful in the implementation of a :attr:`tp_getattro` or</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_299">299+</td><td nowrap="nowrap"><span class="diff_add"> :attr:`tp_getattr` handler that does not use the</span></td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="from26_274">274-</td><td nowrap="nowrap"> <span class="diff_sub"> handler that does not use the</span> :cfunc:`PyObject_GenericGetAttr` function.</td></tr> +<tr><td class="diff_next"></td><td class="diff_header" id="to26_300">300+</td><td nowrap="nowrap"> :cfunc:`PyObject_GenericGetAttr` function.</td></tr> + </tbody> + </table> + <table class="diff" summary="Legends"> + <tr> <th colspan="2"> Legends </th> </tr> + <tr> <td> <table border="" summary="Colors"> + <tr><th> Colors </th> </tr> + <tr><td class="diff_add"> Added </td></tr> + <tr><td class="diff_chg">Changed</td> </tr> + <tr><td class="diff_sub">Deleted</td> </tr> + </table></td> + <td> <table border="" summary="Links"> + <tr><th colspan="2"> Links </th> </tr> + <tr><td>(f)irst change</td> </tr> + <tr><td>(n)ext change</td> </tr> + <tr><td>(t)op</td> </tr> + </table></td> </tr> + </table> +</body> + +</html> ======================================= ***Additional files exist in this changeset.*** ============================================================================== Revision: 013b5348d951 Author: Naoki INADA <inada****@klab*****> Date: Sat Mar 19 08:34:47 2011 Log: merge http://code.google.com/p/python-doc-ja/source/detail?r=013b5348d951
