Changeset 391 for python/trunk/Doc/faq/extending.rst
- Timestamp:
- Mar 19, 2014, 11:31:01 PM (11 years ago)
- Location:
- python/trunk
- Files:
-
- 2 edited
-
. (modified) (1 prop)
-
Doc/faq/extending.rst (modified) (16 diffs)
Legend:
- Unmodified
- Added
- Removed
-
python/trunk
-
Property svn:mergeinfo
set to
/python/vendor/Python-2.7.6 merged eligible /python/vendor/current merged eligible
-
Property svn:mergeinfo
set to
-
python/trunk/Doc/faq/extending.rst
r2 r391 3 3 ======================= 4 4 5 .. contents:: 5 .. only:: html 6 7 .. contents:: 6 8 7 9 .. highlight:: c … … 26 28 C++ objects with constructors are probably not a good idea. 27 29 30 31 .. _c-wrapper-software: 28 32 29 33 Writing C is hard; are there any alternatives? … … 52 56 <http://cxx.sourceforge.net/>`_ `Boost 53 57 <http://www.boost.org/libs/python/doc/index.html>`_, or `Weave 54 <http://www.scipy.org/ site_content/weave>`_ are also alternatives for wrapping58 <http://www.scipy.org/Weave>`_ are also alternatives for wrapping 55 59 C++ libraries. 56 60 … … 59 63 ----------------------------------------------------- 60 64 61 The highest-level function to do this is :c func:`PyRun_SimpleString` which takes65 The highest-level function to do this is :c:func:`PyRun_SimpleString` which takes 62 66 a single string argument to be executed in the context of the module 63 67 ``__main__`` and returns 0 for success and -1 when an exception occurred 64 68 (including ``SyntaxError``). If you want more control, use 65 :c func:`PyRun_String`; see the source for :cfunc:`PyRun_SimpleString` in69 :c:func:`PyRun_String`; see the source for :c:func:`PyRun_SimpleString` in 66 70 ``Python/pythonrun.c``. 67 71 … … 70 74 --------------------------------------------------------- 71 75 72 Call the function :c func:`PyRun_String` from the previous question with the73 start symbol :c data:`Py_eval_input`; it parses an expression, evaluates it and76 Call the function :c:func:`PyRun_String` from the previous question with the 77 start symbol :c:data:`Py_eval_input`; it parses an expression, evaluates it and 74 78 returns its value. 75 79 … … 78 82 ----------------------------------------------- 79 83 80 That depends on the object's type. If it's a tuple, :c func:`PyTuple_Size`81 returns its length and :c func:`PyTuple_GetItem` returns the item at a specified82 index. Lists have similar functions, :c func:`PyListSize` and83 :c func:`PyList_GetItem`.84 85 For strings, :c func:`PyString_Size` returns its length and86 :c func:`PyString_AsString` a pointer to its value. Note that Python strings may87 contain null bytes so C's :c func:`strlen` should not be used.84 That depends on the object's type. If it's a tuple, :c:func:`PyTuple_Size` 85 returns its length and :c:func:`PyTuple_GetItem` returns the item at a specified 86 index. Lists have similar functions, :c:func:`PyListSize` and 87 :c:func:`PyList_GetItem`. 88 89 For strings, :c:func:`PyString_Size` returns its length and 90 :c:func:`PyString_AsString` a pointer to its value. Note that Python strings may 91 contain null bytes so C's :c:func:`strlen` should not be used. 88 92 89 93 To test the type of an object, first make sure it isn't *NULL*, and then use 90 :c func:`PyString_Check`, :cfunc:`PyTuple_Check`, :cfunc:`PyList_Check`, etc.94 :c:func:`PyString_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc. 91 95 92 96 There is also a high-level API to Python objects which is provided by the 93 97 so-called 'abstract' interface -- read ``Include/abstract.h`` for further 94 98 details. It allows interfacing with any kind of Python sequence using calls 95 like :c func:`PySequence_Length`, :cfunc:`PySequence_GetItem`, etc.) as well as99 like :c:func:`PySequence_Length`, :c:func:`PySequence_GetItem`, etc.) as well as 96 100 many other useful protocols. 97 101 … … 102 106 You can't. Use ``t = PyTuple_New(n)`` instead, and fill it with objects using 103 107 ``PyTuple_SetItem(t, i, o)`` -- note that this "eats" a reference count of 104 ``o``, so you have to :c func:`Py_INCREF` it. Lists have similar functions108 ``o``, so you have to :c:func:`Py_INCREF` it. Lists have similar functions 105 109 ``PyList_New(n)`` and ``PyList_SetItem(l, i, o)``. Note that you *must* set all 106 110 the tuple items to some value before you pass the tuple to Python code -- … … 111 115 ---------------------------------------- 112 116 113 The :c func:`PyObject_CallMethod` function can be used to call an arbitrary117 The :c:func:`PyObject_CallMethod` function can be used to call an arbitrary 114 118 method of an object. The parameters are the object, the name of the method to 115 call, a format string like that used with :c func:`Py_BuildValue`, and the119 call, a format string like that used with :c:func:`Py_BuildValue`, and the 116 120 argument values:: 117 121 … … 121 125 122 126 This works for any object that has methods -- whether built-in or user-defined. 123 You are responsible for eventually :c func:`Py_DECREF`\ 'ing the return value.127 You are responsible for eventually :c:func:`Py_DECREF`\ 'ing the return value. 124 128 125 129 To call, e.g., a file object's "seek" method with arguments 10, 0 (assuming the … … 134 138 } 135 139 136 Note that since :c func:`PyObject_CallObject` *always* wants a tuple for the140 Note that since :c:func:`PyObject_CallObject` *always* wants a tuple for the 137 141 argument list, to call a function without arguments, pass "()" for the format, 138 142 and to call a function with one argument, surround the argument in parentheses, … … 185 189 attr = PyObject_GetAttrString(module, "<attrname>"); 186 190 187 Calling :c func:`PyObject_SetAttrString` to assign to variables in the module191 Calling :c:func:`PyObject_SetAttrString` to assign to variables in the module 188 192 also works. 189 193 … … 198 202 Python type around a C structure (pointer) type will also work for C++ objects. 199 203 200 For C++ libraries, you can look at `SIP 201 <http://www.riverbankcomputing.co.uk/sip/>`_, `CXX 202 <http://cxx.sourceforge.net/>`_, `Boost 203 <http://www.boost.org/libs/python/doc/index.html>`_, `Weave 204 <http://www.scipy.org/site_content/weave>`_ or `SWIG <http://www.swig.org>`_ 204 For C++ libraries, see :ref:`c-wrapper-software`. 205 205 206 206 … … 270 270 behavior sufficiently. IDLE uses this, for example. 271 271 272 The easiest way to do it in C is to call :c func:`PyRun_InteractiveLoop` (perhaps272 The easiest way to do it in C is to call :c:func:`PyRun_InteractiveLoop` (perhaps 273 273 in a separate thread) and let the Python interpreter handle the input for 274 you. You can also set the :c func:`PyOS_ReadlineFunctionPointer` to point at your274 you. You can also set the :c:func:`PyOS_ReadlineFunctionPointer` to point at your 275 275 custom input function. See ``Modules/readline.c`` and ``Parser/myreadline.c`` 276 276 for more hints. … … 278 278 However sometimes you have to run the embedded Python interpreter in the same 279 279 thread as your rest application and you can't allow the 280 :c func:`PyRun_InteractiveLoop` to stop while waiting for user input. The one281 solution then is to call :c func:`PyParser_ParseString` and test for ``e.error``280 :c:func:`PyRun_InteractiveLoop` to stop while waiting for user input. The one 281 solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error`` 282 282 equal to ``E_EOF``, which means the input is incomplete). Here's a sample code 283 283 fragment, untested, inspired by code from Alex Farber:: … … 310 310 311 311 Another solution is trying to compile the received string with 312 :c func:`Py_CompileString`. If it compiles without errors, try to execute the313 returned code object by calling :c func:`PyEval_EvalCode`. Otherwise save the312 :c:func:`Py_CompileString`. If it compiles without errors, try to execute the 313 returned code object by calling :c:func:`PyEval_EvalCode`. Otherwise save the 314 314 input for later. If the compilation fails, find out if it's an error or just 315 315 more input is required - by extracting the message string from the exception … … 463 463 Unicode. This only causes the link failure if the extension uses any of the 464 464 ``PyUnicode_*()`` functions. It is also a problem if an extension uses any of 465 the Unicode-related format specifiers for :c func:`Py_BuildValue` (or similar) or466 parameter specifications for :c func:`PyArg_ParseTuple`.465 the Unicode-related format specifiers for :c:func:`Py_BuildValue` (or similar) or 466 parameter specifications for :c:func:`PyArg_ParseTuple`. 467 467 468 468 You can check the size of the Unicode character a Python interpreter is using by
Note:
See TracChangeset
for help on using the changeset viewer.
