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

2000年3月21日 11:32:22 -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:
A number of minor consistency fixes and wording changes.
Explain how *not* to include the Python header file; omniORBpy gets it 
wrong on multi-platform installs on Unix!
Index: api.tex
===================================================================
RCS file: /projects/cvsroot/python/dist/src/Doc/api/api.tex,v
retrieving revision 1.56.2.19
retrieving revision 1.56.2.20
diff -C2 -r1.56.2.19 -r1.56.2.20
*** api.tex	2000年03月16日 15:11:15	1.56.2.19
--- api.tex	2000年03月21日 16:32:18	1.56.2.20
***************
*** 105,109 ****
--- 105,117 ----
 the installation directory specified to the installer.

+ To include the headers, place both directories (if different) on your
+ compiler's search path for includes. Do \emph{not} place the parent
+ directories on the search path and then use
+ \samp{\#include <python1.5/Python.h>}; this will break on
+ multi-platform builds since the platform independent headers under
+ \envvar{prefix} include the platform specific headers from
+ \envvar{exec_prefix}.

+ 
 \section{Objects, Types and Reference Counts \label{objects}}

***************
*** 114,121 ****
 Python language in most situations (e.g., assignments, scope rules,
 and argument passing), it is only fitting that they should be
! represented by a single C type. All Python objects live on the heap:
! you never declare an automatic or static variable of type
 \ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can 
! be declared.

 All Python objects (even Python integers) have a \dfn{type} and a
--- 122,131 ----
 Python language in most situations (e.g., assignments, scope rules,
 and argument passing), it is only fitting that they should be
! represented by a single C type. Almost all Python objects live on the
! heap: you never declare an automatic or static variable of type
 \ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can 
! be declared. The sole exception are the type objects\obindex{type};
! since these must never be deallocated, they are typically static
! \ctype{PyTypeObject} objects.

 All Python objects (even Python integers) have a \dfn{type} and a
***************
*** 1921,1927 ****
 object.

! More information on the buffer interface is provided in chapter
! \ref{newTypes}, under the description for
! \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.

 A ``buffer object'' is defined in the \file{bufferobject.h} header
--- 1931,1937 ----
 object.

! More information on the buffer interface is provided in the section
! ``Buffer Object Structures'' (section \ref{buffer-structs}), under
! the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.

 A ``buffer object'' is defined in the \file{bufferobject.h} header
***************
*** 3569,3573 ****
 Note that in the three examples above, the buffer is always
 manipulated via functions/macros belonging to the same set. Indeed, it
! is highly recommended to use the same memory API family for a given
 memory block, so that the risk of mixing different allocators is
 reduced to a minimum. The following code sequence contains two errors,
--- 3579,3583 ----
 Note that in the three examples above, the buffer is always
 manipulated via functions/macros belonging to the same set. Indeed, it
! is required to use the same memory API family for a given
 memory block, so that the risk of mixing different allocators is
 reduced to a minimum. The following code sequence contains two errors,
***************
*** 3672,3678 ****

 The buffer interface exports a model where an object can expose its
! internal data as a set of chunks of data, each chunk specified as a
! pointer/length pair. These chunks are called ``segments'' and are
! presumed to be non-contiguous in memory.

 If an object does not export the buffer interface, then its
--- 3682,3688 ----

 The buffer interface exports a model where an object can expose its
! internal data as a set of chunks of data, where each chunk is
! specified as a pointer/length pair. These chunks are called
! \dfn{segments} and are presumed to be non-contiguous in memory.

 If an object does not export the buffer interface, then its
***************
*** 3681,3685 ****
 a \ctype{PyBufferProcs} structure.

! \emph{Note:} It is very important that your
 \ctype{PyTypeObject} structure uses \code{Py_TPFLAGS_DEFAULT} for the
 value of the \member{tp_flags} member rather than \code{0}. This
--- 3691,3695 ----
 a \ctype{PyBufferProcs} structure.

! \strong{Note:} It is very important that your
 \ctype{PyTypeObject} structure uses \code{Py_TPFLAGS_DEFAULT} for the
 value of the \member{tp_flags} member rather than \code{0}. This
***************
*** 3711,3716 ****
 The last slot is \member{bf_getcharbuffer}, of type
 \ctype{getcharbufferproc}. This slot will only be present if the
! \code{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in
! \member{tp_flags} of the object's \ctype{PyTypeObject}. Before using
 this slot, the caller should test whether it is present by using the
 \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function.
--- 3721,3726 ----
 The last slot is \member{bf_getcharbuffer}, of type
 \ctype{getcharbufferproc}. This slot will only be present if the
! \code{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
! \member{tp_flags} field of the object's \ctype{PyTypeObject}. Before using
 this slot, the caller should test whether it is present by using the
 \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function.
***************
*** 3726,3730 ****
 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.
--- 3736,3740 ----
 have character-based content.

! \strong{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.