[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