diff options
Diffstat (limited to 'Doc/faq')
| -rw-r--r-- | Doc/faq/extending.rst | 54 | ||||
| -rw-r--r-- | Doc/faq/gui.rst | 4 | ||||
| -rw-r--r-- | Doc/faq/programming.rst | 2 | ||||
| -rw-r--r-- | Doc/faq/windows.rst | 2 |
4 files changed, 31 insertions, 31 deletions
diff --git a/Doc/faq/extending.rst b/Doc/faq/extending.rst index 737ef7c..59e5422 100644 --- a/Doc/faq/extending.rst +++ b/Doc/faq/extending.rst @@ -63,41 +63,41 @@ C++ libraries. How can I execute arbitrary Python statements from C? ----------------------------------------------------- -The highest-level function to do this is :cfunc:`PyRun_SimpleString` which takes +The highest-level function to do this is :c:func:`PyRun_SimpleString` which takes a single string argument to be executed in the context of the module ``__main__`` and returns 0 for success and -1 when an exception occurred (including ``SyntaxError``). If you want more control, use -:cfunc:`PyRun_String`; see the source for :cfunc:`PyRun_SimpleString` in +:c:func:`PyRun_String`; see the source for :c:func:`PyRun_SimpleString` in ``Python/pythonrun.c``. How can I evaluate an arbitrary Python expression from C? --------------------------------------------------------- -Call the function :cfunc:`PyRun_String` from the previous question with the -start symbol :cdata:`Py_eval_input`; it parses an expression, evaluates it and +Call the function :c:func:`PyRun_String` from the previous question with the +start symbol :c:data:`Py_eval_input`; it parses an expression, evaluates it and returns its value. How do I extract C values from a Python object? ----------------------------------------------- -That depends on the object's type. If it's a tuple, :cfunc:`PyTuple_Size` -returns its length and :cfunc:`PyTuple_GetItem` returns the item at a specified -index. Lists have similar functions, :cfunc:`PyListSize` and -:cfunc:`PyList_GetItem`. +That depends on the object's type. If it's a tuple, :c:func:`PyTuple_Size` +returns its length and :c:func:`PyTuple_GetItem` returns the item at a specified +index. Lists have similar functions, :c:func:`PyListSize` and +:c:func:`PyList_GetItem`. -For strings, :cfunc:`PyString_Size` returns its length and -:cfunc:`PyString_AsString` a pointer to its value. Note that Python strings may -contain null bytes so C's :cfunc:`strlen` should not be used. +For strings, :c:func:`PyString_Size` returns its length and +:c:func:`PyString_AsString` a pointer to its value. Note that Python strings may +contain null bytes so C's :c:func:`strlen` should not be used. To test the type of an object, first make sure it isn't *NULL*, and then use -:cfunc:`PyString_Check`, :cfunc:`PyTuple_Check`, :cfunc:`PyList_Check`, etc. +:c:func:`PyString_Check`, :c:func:`PyTuple_Check`, :c:func:`PyList_Check`, etc. There is also a high-level API to Python objects which is provided by the so-called 'abstract' interface -- read ``Include/abstract.h`` for further details. It allows interfacing with any kind of Python sequence using calls -like :cfunc:`PySequence_Length`, :cfunc:`PySequence_GetItem`, etc.) as well as +like :c:func:`PySequence_Length`, :c:func:`PySequence_GetItem`, etc.) as well as many other useful protocols. @@ -106,7 +106,7 @@ How do I use Py_BuildValue() to create a tuple of arbitrary length? You can't. Use ``t = PyTuple_New(n)`` instead, and fill it with objects using ``PyTuple_SetItem(t, i, o)`` -- note that this "eats" a reference count of -``o``, so you have to :cfunc:`Py_INCREF` it. Lists have similar functions +``o``, so you have to :c:func:`Py_INCREF` it. Lists have similar functions ``PyList_New(n)`` and ``PyList_SetItem(l, i, o)``. Note that you *must* set all the tuple items to some value before you pass the tuple to Python code -- ``PyTuple_New(n)`` initializes them to NULL, which isn't a valid Python value. @@ -115,9 +115,9 @@ the tuple items to some value before you pass the tuple to Python code -- How do I call an object's method from C? ---------------------------------------- -The :cfunc:`PyObject_CallMethod` function can be used to call an arbitrary +The :c:func:`PyObject_CallMethod` function can be used to call an arbitrary method of an object. The parameters are the object, the name of the method to -call, a format string like that used with :cfunc:`Py_BuildValue`, and the +call, a format string like that used with :c:func:`Py_BuildValue`, and the argument values:: PyObject * @@ -125,7 +125,7 @@ argument values:: char *arg_format, ...); This works for any object that has methods -- whether built-in or user-defined. -You are responsible for eventually :cfunc:`Py_DECREF`\ 'ing the return value. +You are responsible for eventually :c:func:`Py_DECREF`\ 'ing the return value. To call, e.g., a file object's "seek" method with arguments 10, 0 (assuming the file object pointer is "f"):: @@ -138,7 +138,7 @@ file object pointer is "f"):: Py_DECREF(res); } -Note that since :cfunc:`PyObject_CallObject` *always* wants a tuple for the +Note that since :c:func:`PyObject_CallObject` *always* wants a tuple for the argument list, to call a function without arguments, pass "()" for the format, and to call a function with one argument, surround the argument in parentheses, e.g. "(i)". @@ -189,7 +189,7 @@ module) as follows:: attr = PyObject_GetAttrString(module, "<attrname>"); -Calling :cfunc:`PyObject_SetAttrString` to assign to variables in the module +Calling :c:func:`PyObject_SetAttrString` to assign to variables in the module also works. @@ -270,16 +270,16 @@ the input is invalid. In Python you can use the :mod:`codeop` module, which approximates the parser's behavior sufficiently. IDLE uses this, for example. -The easiest way to do it in C is to call :cfunc:`PyRun_InteractiveLoop` (perhaps +The easiest way to do it in C is to call :c:func:`PyRun_InteractiveLoop` (perhaps in a separate thread) and let the Python interpreter handle the input for -you. You can also set the :cfunc:`PyOS_ReadlineFunctionPointer` to point at your +you. You can also set the :c:func:`PyOS_ReadlineFunctionPointer` to point at your custom input function. See ``Modules/readline.c`` and ``Parser/myreadline.c`` for more hints. However sometimes you have to run the embedded Python interpreter in the same thread as your rest application and you can't allow the -:cfunc:`PyRun_InteractiveLoop` to stop while waiting for user input. The one -solution then is to call :cfunc:`PyParser_ParseString` and test for ``e.error`` +:c:func:`PyRun_InteractiveLoop` to stop while waiting for user input. The one +solution then is to call :c:func:`PyParser_ParseString` and test for ``e.error`` equal to ``E_EOF``, which means the input is incomplete). Here's a sample code fragment, untested, inspired by code from Alex Farber:: @@ -310,8 +310,8 @@ fragment, untested, inspired by code from Alex Farber:: } Another solution is trying to compile the received string with -:cfunc:`Py_CompileString`. If it compiles without errors, try to execute the -returned code object by calling :cfunc:`PyEval_EvalCode`. Otherwise save the +:c:func:`Py_CompileString`. If it compiles without errors, try to execute the +returned code object by calling :c:func:`PyEval_EvalCode`. Otherwise save the input for later. If the compilation fails, find out if it's an error or just more input is required - by extracting the message string from the exception tuple and comparing it to the string "unexpected EOF while parsing". Here is a @@ -463,8 +463,8 @@ This can easily occur when using pre-built extension packages. RedHat Linux 7.x, in particular, provided a "python2" binary that is compiled with 4-byte Unicode. This only causes the link failure if the extension uses any of the ``PyUnicode_*()`` functions. It is also a problem if an extension uses any of -the Unicode-related format specifiers for :cfunc:`Py_BuildValue` (or similar) or -parameter specifications for :cfunc:`PyArg_ParseTuple`. +the Unicode-related format specifiers for :c:func:`Py_BuildValue` (or similar) or +parameter specifications for :c:func:`PyArg_ParseTuple`. You can check the size of the Unicode character a Python interpreter is using by checking the value of sys.maxunicode: diff --git a/Doc/faq/gui.rst b/Doc/faq/gui.rst index fd6ca0c..dbb3f02 100644 --- a/Doc/faq/gui.rst +++ b/Doc/faq/gui.rst @@ -123,7 +123,7 @@ SAM (stand-alone modules), which is part of the Tix distribution (http://tix.sourceforge.net/). Build Tix with SAM enabled, perform the appropriate call to -:cfunc:`Tclsam_init`, etc. inside Python's +:c:func:`Tclsam_init`, etc. inside Python's :file:`Modules/tkappinit.c`, and link with libtclsam and libtksam (you might include the Tix libraries as well). @@ -132,7 +132,7 @@ Can I have Tk events handled while waiting for I/O? --------------------------------------------------- Yes, and you don't even need threads! But you'll have to restructure your I/O -code a bit. Tk has the equivalent of Xt's :cfunc:`XtAddInput()` call, which allows you +code a bit. Tk has the equivalent of Xt's :c:func:`XtAddInput()` call, which allows you to register a callback function which will be called from the Tk mainloop when I/O is possible on a file descriptor. Here's what you need:: diff --git a/Doc/faq/programming.rst b/Doc/faq/programming.rst index dff6074..fdfd9ec 100644 --- a/Doc/faq/programming.rst +++ b/Doc/faq/programming.rst @@ -989,7 +989,7 @@ and then convert decimal strings to numeric values using :func:`int` or if the line uses something other than whitespace as a separator. For more complicated input parsing, regular expressions are more powerful -than C's :cfunc:`sscanf` and better suited for the task. +than C's :c:func:`sscanf` and better suited for the task. What does 'UnicodeDecodeError' or 'UnicodeEncodeError' error mean? diff --git a/Doc/faq/windows.rst b/Doc/faq/windows.rst index bfd03f7..6266d10 100644 --- a/Doc/faq/windows.rst +++ b/Doc/faq/windows.rst @@ -541,7 +541,7 @@ assumed by the Python interpreter it won't work. The Python 1.5.* DLLs (``python15.dll``) are all compiled with MS VC++ 5.0 and with multithreading-DLL options (``/MD``). -If you can't change compilers or flags, try using :cfunc:`Py_RunSimpleString`. +If you can't change compilers or flags, try using :c:func:`Py_RunSimpleString`. A trick to get it to run an arbitrary file is to construct a call to :func:`execfile` with the name of your file as argument. |