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

Fred L. Drake fdrake@weyr.cnri.reston.va.us
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}