[Python-checkins] CVS: python/dist/src/Doc/api api.tex,1.56.2.15,1.56.2.16

Fri, 3 Mar 2000 11:32:50 -0500 (EST)

Update of /projects/cvsroot/python/dist/src/Doc/api
In directory weyr:/home/fdrake/projects/python/Doc-152p2/api
Modified Files:
 Tag: release152p1-patches
	api.tex 
Log Message:
Update to the new markup so that a better index is generated in a few
cases.
Restructure the "Defining New Types" chapter (incomplete).
Index: api.tex
===================================================================
RCS file: /projects/cvsroot/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.56.2.15
retrieving revision 1.56.2.16
diff -C2 -r1.56.2.15 -r1.56.2.16
*** api.tex	2000年02月29日 16:12:55	1.56.2.15
--- api.tex	2000年03月03日 16:32:47	1.56.2.16
***************
*** 1122,1126 ****
 \end{cfuncdesc}

! \begin{ctypedesc}{struct _frozen}
 This is the structure type definition for frozen module descriptors,
 as generated by the \program{freeze}\index{freeze utility} utility
--- 1122,1126 ----
 \end{cfuncdesc}

! \begin{ctypedesc}[_frozen]{struct _frozen}
 This is the structure type definition for frozen module descriptors,
 as generated by the \program{freeze}\index{freeze utility} utility
***************
*** 3162,3167 ****
 \end{cfuncdesc}

! % XXX These aren't really C types, but the ctypedesc macro is the simplest!
! \begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
 This macro expands to
 \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
--- 3162,3166 ----
 \end{cfuncdesc}

! \begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
 This macro expands to
 \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
***************
*** 3170,3176 ****
 discussion of this macro. It is a no-op when thread support is
 disabled at compile time.
! \end{ctypedesc}

! \begin{ctypedesc}{Py_END_ALLOW_THREADS}
 This macro expands to
 \samp{PyEval_RestoreThread(_save); \}}.
--- 3169,3175 ----
 discussion of this macro. It is a no-op when thread support is
 disabled at compile time.
! \end{csimplemacrodesc}

! \begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
 This macro expands to
 \samp{PyEval_RestoreThread(_save); \}}.
***************
*** 3179,3197 ****
 discussion of this macro. It is a no-op when thread support is
 disabled at compile time.
! \end{ctypedesc}

! \begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
 This macro expands to \samp{PyEval_RestoreThread(_save);} i.e. it
 is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
 brace. It is a no-op when thread support is disabled at compile
 time.
! \end{ctypedesc}

! \begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
 This macro expands to \samp{_save = PyEval_SaveThread();} i.e. it is
 equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
 and variable declaration. It is a no-op when thread support is
 disabled at compile time.
! \end{ctypedesc}

 All of the following functions are only available when thread support
--- 3178,3196 ----
 discussion of this macro. It is a no-op when thread support is
 disabled at compile time.
! \end{csimplemacrodesc}

! \begin{csimplemacrodesc}{Py_BEGIN_BLOCK_THREADS}
 This macro expands to \samp{PyEval_RestoreThread(_save);} i.e. it
 is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
 brace. It is a no-op when thread support is disabled at compile
 time.
! \end{csimplemacrodesc}

! \begin{csimplemacrodesc}{Py_BEGIN_UNBLOCK_THREADS}
 This macro expands to \samp{_save = PyEval_SaveThread();} i.e. it is
 equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
 and variable declaration. It is a no-op when thread support is
 disabled at compile time.
! \end{csimplemacrodesc}

 All of the following functions are only available when thread support
***************
*** 3487,3490 ****
--- 3486,3498 ----
 Py_BuildValue

+ DL_IMPORT
+ 
+ Py*_Check
+ 
+ _Py_NoneStruct
+ 
+ 
+ \section{Common Object Structures \label{common-structs}}
+ 
 PyObject, PyVarObject

***************
*** 3497,3534 ****
 setattrofunc, cmpfunc, reprfunc, hashfunc

- \begin{ctypedesc}{int (*getreadbufferproc) (PyObject *self, int segment,
- void **ptrptr)}
- \end{ctypedesc}

! \begin{ctypedesc}{int (*getwritebufferproc) (PyObject *self, int segment,
! void **ptrptr)}
! Return a pointer to a writable memory buffer in \code{*\var{ptrptr}};
! the memory buffer must correspond to buffer segment \var{segment}.
! Must return \code{-1} and set an exception on error.
! \exception{TypeError} should be raised if the object only supports
! read-only buffers, and \exception{SystemError} should be raised when
! \var{segment} specifies a segment that doesn't exist.
! % Why doesn't it raise ValueError for this one?
! % GJS: because you shouldn't be calling it with an invalid
! % segment. That indicates a blatant programming error in the C
! % code.
! \end{ctypedesc}

! \begin{ctypedesc}{int (*getsegcountproc) (PyObject *self, int *lenp)}
! \end{ctypedesc}

! \begin{ctypedesc}{int (*getcharbufferproc) (PyObject *self, int segment,
! const char **ptrptr)}
! \end{ctypedesc}

 PyNumberMethods

 PySequenceMethods

- PyMappingMethods

! \begin{ctypedesc}{PyBufferProcs}
! \code{PyBufferProcs} defines a set of slots for a Python type
! object. These slots are used to implement the ``buffer interface.''

 The buffer interface exports a model where an object can expose its
--- 3505,3526 ----
 setattrofunc, cmpfunc, reprfunc, hashfunc

! \section{Mapping Object Structures \label{mapping-structs}}

! PyMappingMethods

! 
! \section{Number Object Structures \label{number-structs}}

 PyNumberMethods

+ 
+ \section{Sequence Object Structures \label{sequence-structs}}
+ 
 PySequenceMethods

! \section{Buffer Object Structures \label{buffer-structs}}
! \sectionauthor{Greg J. Stein}{greg@lyra.org}

 The buffer interface exports a model where an object can expose its
***************
*** 3539,3544 ****
 If an object does not export the buffer interface, then its
 \member{tp_as_buffer} member in the \ctype{PyTypeObject} structure
! should be \NULL{}. Otherwise, \member{tp_as_buffer} will point to a
! \ctype{PyBufferProcs} structure.

 \emph{Note:} it is very important that your
--- 3531,3536 ----
 If an object does not export the buffer interface, then its
 \member{tp_as_buffer} member in the \ctype{PyTypeObject} structure
! should be \NULL{}. Otherwise, the \member{tp_as_buffer} will point to
! a \ctype{PyBufferProcs} structure.

 \emph{Note:} it is very important that your
***************
*** 3550,3553 ****
--- 3542,3550 ----
 to be able to test for its presence before using it.

+ 
+ \begin{ctypedesc}{PyBufferProcs}
+ \code{PyBufferProcs} defines a set of slots for a Python type
+ object. These slots are used to implement the ``buffer interface.''
+ 
 The first slot in the \ctype{PyBufferProcs} structure is
 \member{bf_getreadbuffer}, which has type
***************
*** 3593,3606 ****
 binary in nature, and those which have character-based content.

! \emph{Note:} the current policy seems to state that these
! characters may be multi-byte characters. This implies that a buffer
! size of \var{N} does not mean there are \var{N} characters present.
 \end{ctypedesc}

! DL_IMPORT

! Py*_Check

! _Py_NoneStruct

--- 3590,3623 ----
 binary in nature, and those which have character-based content.

! \emph{Note:} The current policy seems to state that these characters
! may be multi-byte characters. This implies that a buffer size of
! \var{N} does not mean there are \var{N} characters present.
 \end{ctypedesc}

! \begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
! (PyObject *self, int segment, void **ptrptr)}
! \end{ctypedesc}

! \begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
! (PyObject *self, int segment, void **ptrptr)}
! Return a pointer to a writable memory buffer in \code{*\var{ptrptr}};
! the memory buffer must correspond to buffer segment \var{segment}.
! Must return \code{-1} and set an exception on error.
! \exception{TypeError} should be raised if the object only supports
! read-only buffers, and \exception{SystemError} should be raised when
! \var{segment} specifies a segment that doesn't exist.
! % Why doesn't it raise ValueError for this one?
! % GJS: because you shouldn't be calling it with an invalid
! % segment. That indicates a blatant programming error in the C
! % code.
! \end{ctypedesc}

! \begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
! (PyObject *self, int *lenp)}
! \end{ctypedesc}
! 
! \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
! (PyObject *self, int segment, const char **ptrptr)}
! \end{ctypedesc}