[Python-checkins] r59262 - in python/trunk/Doc: ACKS.txt c-api/init.rst c-api/utilities.rst c-api/veryhigh.rst extending/extending.rst
georg.brandl
python-checkins at python.org
Sat Dec 1 23:24:47 CET 2007
Author: georg.brandl
Date: Sat Dec 1 23:24:47 2007
New Revision: 59262
Modified:
python/trunk/Doc/ACKS.txt
python/trunk/Doc/c-api/init.rst
python/trunk/Doc/c-api/utilities.rst
python/trunk/Doc/c-api/veryhigh.rst
python/trunk/Doc/extending/extending.rst
Log:
Document PyEval_* functions from ceval.c.
Credits to Michael Sloan from GHOP.
Modified: python/trunk/Doc/ACKS.txt
==============================================================================
--- python/trunk/Doc/ACKS.txt (original)
+++ python/trunk/Doc/ACKS.txt Sat Dec 1 23:24:47 2007
@@ -162,6 +162,7 @@
* Justin Sheehy
* Michael Simcich
* Ionel Simionescu
+* Michael Sloan
* Gregory P. Smith
* Roy Smith
* Clay Spence
Modified: python/trunk/Doc/c-api/init.rst
==============================================================================
--- python/trunk/Doc/c-api/init.rst (original)
+++ python/trunk/Doc/c-api/init.rst Sat Dec 1 23:24:47 2007
@@ -621,6 +621,14 @@
deadlock ensues. (This function is available even when thread support is
disabled at compile time.)
+
+.. cfunction:: void PyEval_ReInitThreads()
+
+ This function is called from :cfunc:`PyOS_AfterFork` to ensure that newly
+ created child processes don't hold locks referring to threads which
+ are not running in the child process.
+
+
The following macros are normally used without a trailing semicolon; look for
example usage in the Python source distribution.
@@ -892,6 +900,46 @@
:cfunc:`PyEval_SetProfile`, except the tracing function does receive line-number
events.
+.. cfunction:: PyObject* PyEval_GetCallStats(PyObject *self)
+
+ Return a tuple of function call counts. There are constants defined for the
+ positions within the tuple:
+
+ +-------------------------------+-------+
+ | Name | Value |
+ +===============================+=======+
+ | :const:`PCALL_ALL` | 0 |
+ +-------------------------------+-------+
+ | :const:`PCALL_FUNCTION` | 1 |
+ +-------------------------------+-------+
+ | :const:`PCALL_FAST_FUNCTION` | 2 |
+ +-------------------------------+-------+
+ | :const:`PCALL_FASTER_FUNCTION`| 3 |
+ +-------------------------------+-------+
+ | :const:`PCALL_METHOD` | 4 |
+ +-------------------------------+-------+
+ | :const:`PCALL_BOUND_METHOD` | 5 |
+ +-------------------------------+-------+
+ | :const:`PCALL_CFUNCTION` | 6 |
+ +-------------------------------+-------+
+ | :const:`PCALL_TYPE` | 7 |
+ +-------------------------------+-------+
+ | :const:`PCALL_GENERATOR` | 8 |
+ +-------------------------------+-------+
+ | :const:`PCALL_OTHER` | 9 |
+ +-------------------------------+-------+
+ | :const:`PCALL_POP` | 10 |
+ +-------------------------------+-------+
+
+ :const:`PCALL_FAST_FUNCTION` means no argument tuple needs to be created.
+ :const:`PCALL_FASTER_FUNCTION` means that the fast-path frame setup code is used.
+
+ If there is a method call where the call can be optimized by changing
+ the argument tuple and calling the function directly, it gets recorded
+ twice.
+
+ This function is only present if Python is compiled with :const:`CALL_PROFILE`
+ defined.
.. _advanced-debugging:
Modified: python/trunk/Doc/c-api/utilities.rst
==============================================================================
--- python/trunk/Doc/c-api/utilities.rst (original)
+++ python/trunk/Doc/c-api/utilities.rst Sat Dec 1 23:24:47 2007
@@ -1015,3 +1015,52 @@
See the Unix man page :manpage:`atof(2)` for details.
+
+.. _reflection:
+
+Reflection
+==========
+
+.. cfunction:: PyObject* PyEval_GetBuiltins()
+
+ Return a dictionary of the builtins in the current execution frame,
+ or the interpreter of the thread state if no frame is currently executing.
+
+
+.. cfunction:: PyObject* PyEval_GetLocals()
+
+ Return a dictionary of the local variables in the current execution frame,
+ or *NULL* if no frame is currently executing.
+
+
+.. cfunction:: PyObject* PyEval_GetGlobals()
+
+ Return a dictionary of the global variables in the current execution frame,
+ or *NULL* if no frame is currently executing.
+
+
+.. cfunction:: PyFrameObject* PyEval_GetFrame()
+
+ Return the current thread state's frame, which is *NULL* if no frame is
+ currently executing.
+
+
+.. cfunction:: int PyEval_GetRestricted()
+
+ If there is a current frame and it is executing in restricted mode, return true,
+ otherwise false.
+
+
+.. cfunction:: const char* PyEval_GetFuncName(PyObject *func)
+
+ Return the name of *func* if it is a function, class or instance object, else the
+ name of *func*\s type.
+
+
+.. cfunction:: const char* PyEval_GetFuncDesc(PyObject *func)
+
+ Return a description string, depending on the type of *func*.
+ Return values include "()" for functions and methods, " constructor",
+ " instance", and " object". Concatenated with the result of
+ :cfunc:`PyEval_GetFuncName`, the result will be a description of
+ *func*.
Modified: python/trunk/Doc/c-api/veryhigh.rst
==============================================================================
--- python/trunk/Doc/c-api/veryhigh.rst (original)
+++ python/trunk/Doc/c-api/veryhigh.rst Sat Dec 1 23:24:47 2007
@@ -229,6 +229,43 @@
be parsed or compiled.
+.. cfunction:: PyObject* PyEval_EvalCode(PyCodeObject *co, PyObject *globals, PyObject *locals)
+
+ This is a simplified interface to :cfunc:`PyEval_EvalCodeEx`, with just
+ the code object, and the dictionaries of global and local variables.
+ The other arguments are set to *NULL*.
+
+
+.. cfunction:: PyObject* PyEval_EvalCodeEx(PyCodeObject *co, PyObject *globals, PyObject *locals, PyObject **args, int argcount, PyObject **kws, int kwcount, PyObject **defs, int defcount, PyObject *closure)
+
+ Evaluate a precompiled code object, given a particular environment for its
+ evaluation. This environment consists of dictionaries of global and local
+ variables, arrays of arguments, keywords and defaults, and a closure tuple of
+ cells.
+
+
+.. cfunction:: PyObject* PyEval_EvalFrame(PyFrameObject *f)
+
+ Evaluate an execution frame. This is a simplified interface to
+ PyEval_EvalFrameEx, for backward compatibility.
+
+
+.. cfunction:: PyObject* PyEval_EvalFrameEx(PyFrameObject *f, int throwflag)
+
+ This is the main, unvarnished function of Python interpretation. It is
+ literally 2000 lines long. The code object associated with the execution
+ frame *f* is executed, interpreting bytecode and executing calls as needed.
+ The additional *throwflag* parameter can mostly be ignored - if true, then
+ it causes an exception to immediately be thrown; this is used for the
+ :meth:`throw` methods of generator objects.
+
+
+.. cfunction:: int PyEval_MergeCompilerFlags(PyCompilerFlags *cf)
+
+ This function changes the flags of the current evaluation frame, and returns
+ true on success, false on failure.
+
+
.. cvar:: int Py_eval_input
.. index:: single: Py_CompileString()
Modified: python/trunk/Doc/extending/extending.rst
==============================================================================
--- python/trunk/Doc/extending/extending.rst (original)
+++ python/trunk/Doc/extending/extending.rst Sat Dec 1 23:24:47 2007
@@ -471,10 +471,10 @@
:cfunc:`PyEval_CallObject`. This function has two arguments, both pointers to
arbitrary Python objects: the Python function, and the argument list. The
argument list must always be a tuple object, whose length is the number of
-arguments. To call the Python function with no arguments, pass an empty tuple;
-to call it with one argument, pass a singleton tuple. :cfunc:`Py_BuildValue`
-returns a tuple when its format string consists of zero or more format codes
-between parentheses. For example::
+arguments. To call the Python function with no arguments, pass in NULL, or
+an empty tuple; to call it with one argument, pass a singleton tuple.
+:cfunc:`Py_BuildValue` returns a tuple when its format string consists of zero
+or more format codes between parentheses. For example::
int arg;
PyObject *arglist;
@@ -532,9 +532,22 @@
Py_DECREF(result);
Note the placement of ``Py_DECREF(arglist)`` immediately after the call, before
-the error check! Also note that strictly spoken this code is not complete:
+the error check! Also note that strictly speaking this code is not complete:
:cfunc:`Py_BuildValue` may run out of memory, and this should be checked.
+You may also call a function with keyword arguments by using
+:cfunc:`PyEval_CallObjectWithKeywords`. As in the above example, we use
+:cfunc:`Py_BuildValue` to construct the dictionary. ::
+
+ PyObject *dict;
+ ...
+ dict = Py_BuildValue("{s:i}", "name", val);
+ result = PyEval_CallObjectWithKeywords(my_callback, NULL, dict);
+ Py_DECREF(dict);
+ if (result == NULL)
+ return NULL; /* Pass error back */
+ /* Here maybe use the result */
+ Py_DECREF(result);
.. _parsetuple:
More information about the Python-checkins
mailing list