[Python-checkins] python/dist/src/Doc/api abstract.tex, 1.17.2.2, 1.17.2.3 concrete.tex, 1.17.2.2, 1.17.2.3 init.tex, 1.3.2.2, 1.3.2.3 newtypes.tex, 1.13.2.2, 1.13.2.3 refcounts.dat, 1.43.2.1, 1.43.2.2 utilities.tex, 1.5.2.2, 1.5.2.3
jhylton@users.sourceforge.net
jhylton at users.sourceforge.net
Sun Oct 16 07:24:30 CEST 2005
Update of /cvsroot/python/python/dist/src/Doc/api
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv27718/Doc/api
Modified Files:
Tag: ast-branch
abstract.tex concrete.tex init.tex newtypes.tex refcounts.dat
utilities.tex
Log Message:
Merge head to branch (for the last time)
Index: abstract.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/abstract.tex,v
retrieving revision 1.17.2.2
retrieving revision 1.17.2.3
diff -u -d -r1.17.2.2 -r1.17.2.3
--- abstract.tex 7 Jan 2005 06:56:52 -0000 1.17.2.2
+++ abstract.tex 16 Oct 2005 05:23:56 -0000 1.17.2.3
@@ -778,12 +778,6 @@
the Python statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
\end{cfuncdesc}
-\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
- Returns the \var{o} as a tuple on success, and \NULL{} on failure.
- This is equivalent to the Python expression \samp{tuple(\var{o})}.
- \bifuncindex{tuple}
-\end{cfuncdesc}
-
\begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
Return the number of occurrences of \var{value} in \var{o}, that is,
return the number of keys for which \code{\var{o}[\var{key}] ==
@@ -811,9 +805,11 @@
\begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
Return a tuple object with the same contents as the arbitrary
- sequence \var{o}. If \var{o} is a tuple, a new reference will be
- returned, otherwise a tuple will be constructed with the appropriate
- contents.
+ sequence \var{o} or \NULL{} on failure. If \var{o} is a tuple,
+ a new reference will be returned, otherwise a tuple will be
+ constructed with the appropriate contents. This is equivalent
+ to the Python expression \samp{tuple(\var{o})}.
+ \bifuncindex{tuple}
\end{cfuncdesc}
\begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m}
Index: concrete.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/concrete.tex,v
retrieving revision 1.17.2.2
retrieving revision 1.17.2.3
diff -u -d -r1.17.2.2 -r1.17.2.3
--- concrete.tex 7 Jan 2005 06:56:52 -0000 1.17.2.2
+++ concrete.tex 16 Oct 2005 05:23:56 -0000 1.17.2.3
@@ -36,20 +36,20 @@
\end{cvardesc}
\begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
- Returns true if the object \var{o} is a type object, including
- instances of types derived from the standard type object. Returns
+ Return true if the object \var{o} is a type object, including
+ instances of types derived from the standard type object. Return
false in all other cases.
\end{cfuncdesc}
\begin{cfuncdesc}{int}{PyType_CheckExact}{PyObject *o}
[...1572 lines suppressed...]
+
+\begin{cfuncdesc}{int}{PySet_Discard}{PyObject *set, PyObject *key}
+ Return 1 if found and removed, 0 if not found (no action taken),
+ and -1 if an error is encountered. Does not raise \exception{KeyError}
+ for missing keys. Raise a \exception{TypeError} if the \var{key} is
+ unhashable. Unlike the Python \method{discard()} method, this function
+ does not automatically convert unhashable sets into temporary frozensets.
+ Raise \exception{PyExc_SystemError} if \var{set} is an not an instance
+ of \class{set} or its subtype.
+\end{cfuncdesc}
+
+\begin{cfuncdesc}{PyObject*}{PySet_Pop}{PyObject *set}
+ Return a new reference to an arbitrary object in the \var{set},
+ and removes the object from the \var{set}. Return \NULL{} on
+ failure. Raise \exception{KeyError} if the set is empty.
+ Raise a \exception{SystemError} if \var{set} is an not an instance
+ of \class{set} or its subtype.
+\end{cfuncdesc}
+
+
Index: init.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/init.tex,v
retrieving revision 1.3.2.2
retrieving revision 1.3.2.3
diff -u -d -r1.3.2.2 -r1.3.2.3
--- init.tex 7 Jan 2005 06:56:53 -0000 1.3.2.2
+++ init.tex 16 Oct 2005 05:23:56 -0000 1.3.2.3
@@ -131,6 +131,12 @@
objects may affect the wrong (sub-)interpreter's dictionary of
loaded modules. (XXX This is a hard-to-fix bug that will be
addressed in a future release.)
+
+ Also note that the use of this functionality is incompatible with
+ extension modules such as PyObjC and ctypes that use the
+ \cfunction{PyGILState_*} APIs (and this is inherent in the way the
+ \cfunction{PyGILState_*} functions work). Simple things may work,
+ but confusing behavior will always be near.
\end{cfuncdesc}
\begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
@@ -239,9 +245,8 @@
program name (set by \cfunction{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 \character{:} on \UNIX,
- \character{;} on Windows, and \character{\e n} (the \ASCII{}
- newline character) on Macintosh. The returned string points into
+ character. The delimiter character is \character{:} on \UNIX and Mac OS X,
+ \character{;} 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
\code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, which
@@ -272,7 +277,7 @@
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 \code{'sunos5'}. On Macintosh, it is \code{'mac'}. On Windows,
+ is \code{'sunos5'}. On Mac OS X, it is \code{'darwin'}. On Windows,
it is \code{'win'}. The returned string points into static storage;
the caller should not modify its value. The value is available to
Python code as \code{sys.platform}.
@@ -455,19 +460,10 @@
pointer, release the lock, and finally free their thread state data
structure.
-When creating a thread data structure, you need to provide an
-interpreter state data structure. The interpreter state data
-structure holds global data that is shared by all threads in an
-interpreter, for example the module administration
-(\code{sys.modules}). Depending on your needs, you can either create
-a new interpreter state data structure, or share the interpreter state
-data structure used by the Python main thread (to access the latter,
-you must obtain the thread state and access its \member{interp} member;
-this must be done by a thread that is created by Python or by the main
-thread after Python is initialized).
-
-Assuming you have access to an interpreter object, the typical idiom
-for calling into Python from a C thread is
+Beginning with version 2.3, threads can now take advantage of the
+\cfunction{PyGILState_*()} functions to do all of the above
+automatically. The typical idiom for calling into Python from a C
+thread is now:
\begin{verbatim}
PyGILState_STATE gstate;
@@ -481,6 +477,13 @@
PyGILState_Release(gstate);
\end{verbatim}
+Note that the \cfunction{PyGILState_*()} functions assume there is
+only one global interpreter (created automatically by
+\cfunction{Py_Initialize()}). Python still supports the creation of
+additional interpreters (using \cfunction{Py_NewInterpreter()}), but
+mixing multiple interpreters and the \cfunction{PyGILState_*()} API is
+unsupported.
+
\begin{ctypedesc}{PyInterpreterState}
This data structure represents the state shared by a number of
cooperating threads. Threads belonging to the same interpreter
@@ -700,16 +703,16 @@
\end{cfuncdesc}
\begin{cfuncdesc}{PyGILState_STATE}{PyGILState_Ensure}{}
-Ensure that the current thread is ready to call the Python
-C API regardless of the current state of Python, or of its
-thread lock. This may be called as many times as desired
-by a thread as long as each call is matched with a call to
-\cfunction{PyGILState_Release()}.
-In general, other thread-related APIs may
-be used between \cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()} calls as long as the
-thread state is restored to its previous state before the Release().
-For example, normal usage of the \csimplemacro{Py_BEGIN_ALLOW_THREADS}
-and \csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable.
+Ensure that the current thread is ready to call the Python C API
+regardless of the current state of Python, or of its thread lock.
+This may be called as many times as desired by a thread as long as
+each call is matched with a call to \cfunction{PyGILState_Release()}.
+In general, other thread-related APIs may be used between
+\cfunction{PyGILState_Ensure()} and \cfunction{PyGILState_Release()}
+calls as long as the thread state is restored to its previous state
+before the Release(). For example, normal usage of the
+\csimplemacro{Py_BEGIN_ALLOW_THREADS} and
+\csimplemacro{Py_END_ALLOW_THREADS} macros is acceptable.
The return value is an opaque "handle" to the thread state when
\cfunction{PyGILState_Acquire()} was called, and must be passed to
Index: newtypes.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/newtypes.tex,v
retrieving revision 1.13.2.2
retrieving revision 1.13.2.3
diff -u -d -r1.13.2.2 -r1.13.2.3
--- newtypes.tex 7 Jan 2005 06:56:53 -0000 1.13.2.2
+++ newtypes.tex 16 Oct 2005 05:23:56 -0000 1.13.2.3
@@ -191,7 +191,7 @@
int ob_size;
\end{verbatim}
Note that \csimplemacro{PyObject_HEAD} is part of the expansion, and
- that it's own expansion varies depending on the definition of
+ that its own expansion varies depending on the definition of
\csimplemacro{Py_TRACE_REFS}.
\end{csimplemacrodesc}
@@ -1106,6 +1106,13 @@
\begin{cmemberdesc}{PyTypeObject}{descrgetfunc}{tp_descr_get}
An optional pointer to a "descriptor get" function.
+
+ The function signature is
+
+\begin{verbatim}
+PyObject * tp_descr_get(PyObject *self, PyObject *obj, PyObject *type);
+\end{verbatim}
+
XXX blah, blah.
This field is inherited by subtypes.
@@ -1114,9 +1121,16 @@
\begin{cmemberdesc}{PyTypeObject}{descrsetfunc}{tp_descr_set}
An optional pointer to a "descriptor set" function.
- XXX blah, blah.
+ The function signature is
+
+\begin{verbatim}
+int tp_descr_set(PyObject *self, PyObject *obj, PyObject *value);
+\end{verbatim}
This field is inherited by subtypes.
+
+ XXX blah, blah.
+
\end{cmemberdesc}
\begin{cmemberdesc}{PyTypeObject}{long}{tp_dictoffset}
Index: refcounts.dat
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/refcounts.dat,v
retrieving revision 1.43.2.1
retrieving revision 1.43.2.2
diff -u -d -r1.43.2.1 -r1.43.2.2
--- refcounts.dat 28 Apr 2003 17:38:11 -0000 1.43.2.1
+++ refcounts.dat 16 Oct 2005 05:23:57 -0000 1.43.2.2
@@ -1009,6 +1009,24 @@
PySequence_Tuple:PyObject*::+1:
PySequence_Tuple:PyObject*:o:0:
+PySet_Append:int:::
+PySet_Append:PyObject*:set:0:
+PySet_Append:PyObject*:key:+1:
+
+PySet_Contains:int:::
+PySet_Contains:PyObject*:anyset:0:
+PySet_Contains:PyObject*:key:0:
+
+PySet_Discard:int:::
+PySet_Discard:PyObject*:set:0:
+PySet_Discard:PyObject*:key:-1:no effect if key not found
+
+PySet_Pop:PyObject*::0:or returns NULL and raises KeyError if set is empty
+PySet_Pop:PyObject*:set:0:
+
+PySet_Size:int:::
+PySet_Size:PyObject*:anyset:0:
+
PySlice_Check:int:::
PySlice_Check:PyObject*:ob:0:
Index: utilities.tex
===================================================================
RCS file: /cvsroot/python/python/dist/src/Doc/api/utilities.tex,v
retrieving revision 1.5.2.2
retrieving revision 1.5.2.3
diff -u -d -r1.5.2.2 -r1.5.2.3
--- utilities.tex 7 Jan 2005 06:56:53 -0000 1.5.2.2
+++ utilities.tex 16 Oct 2005 05:23:57 -0000 1.5.2.3
@@ -34,7 +34,7 @@
Return true when the interpreter runs out of stack space. This is a
reliable check, but is only available when \constant{USE_STACKCHECK}
is defined (currently on Windows using the Microsoft Visual \Cpp{}
- compiler and on the Macintosh). \constant{USE_CHECKSTACK} will be
+ compiler). \constant{USE_STACKCHECK} will be
defined automatically; you should never change the definition in
your own code.
\end{cfuncdesc}
@@ -539,7 +539,7 @@
Convert a Python integer to a C \ctype{long int}.
\item[\samp{k} (integer) {[unsigned long]}]
- Convert a Python integer to a C \ctype{unsigned long} without
+ Convert a Python integer or long integer to a C \ctype{unsigned long} without
overflow checking. \versionadded{2.3}
\item[\samp{L} (integer) {[PY_LONG_LONG]}]
@@ -548,7 +548,7 @@
\ctype{_int64} on Windows).
\item[\samp{K} (integer) {[unsigned PY_LONG_LONG]}]
- Convert a Python integer to a C \ctype{unsigned 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). \versionadded{2.3}
More information about the Python-checkins
mailing list