cpython-lru_cache-weakref: Doc/api/api.tex annotate

annotate Doc/api/api.tex @ 19283:b865cd5c1925 legacy-trunk

Added comments before recently added/assigned slots in the type object, so the backward compatibility issues will be easier to understand. I only added comments indicating additions and assignments back to Python 2.0.

author	Fred Drake <fdrake@acm.org>
date	Wed, 15 Aug 2001 18:32:33 +0000
parents	d99c1240d0ac
children	b9701538f827

rev	line source
7527 26a8771a4cfd Convert LaTeX support to create a new class of documents. HTML generation Fred Drake <fdrake@acm.org> parents: 7493 diff changeset	1 \documentclass{manual}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	3 \title{Python/C API Reference Manual}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	4
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	5 \input{boilerplate}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	6
15953 8349b4dfc51a Undoing the whitespace patches which sneaked into the earlier patch. Marc-André Lemburg <mal@egenix.com> parents: 15952 diff changeset	7 \makeindex % tell \index to actually write the .idx file
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	8
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	9
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	10 \begin{document}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	11
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	12 \maketitle
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	13
8782 ae3e2eaef9b9 Update to use a separate page for front matter. Fred Drake <fdrake@acm.org> parents: 8138 diff changeset	14 \ifhtml
ae3e2eaef9b9 Update to use a separate page for front matter. Fred Drake <fdrake@acm.org> parents: 8138 diff changeset	15 \chapter*{Front Matter\label{front}}
ae3e2eaef9b9 Update to use a separate page for front matter. Fred Drake <fdrake@acm.org> parents: 8138 diff changeset	16 \fi
ae3e2eaef9b9 Update to use a separate page for front matter. Fred Drake <fdrake@acm.org> parents: 8138 diff changeset	17
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	18 \input{copyright}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	19
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	20 \begin{abstract}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	21
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	22 \noindent
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	23 This manual documents the API used by C and \Cpp{} programmers who
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	24 want to write extension modules or embed Python. It is a companion to
11451 38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	25 \citetitle[../ext/ext.html]{Extending and Embedding the Python
38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	26 Interpreter}, which describes the general principles of extension
38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	27 writing but does not document the API functions in detail.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	28
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	29 \strong{Warning:} The current version of this document is incomplete.
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	30 I hope that it is nevertheless useful. I will continue to work on it,
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	31 and release new versions from time to time, independent from Python
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	32 source code releases.
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	33
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	34 \end{abstract}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	35
7092 8a55643e667f Removed \mytableofcontents; just use \tableofcontents. Fred Drake <fdrake@acm.org> parents: 7081 diff changeset	36 \tableofcontents
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	37
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	38 % XXX Consider moving all this back to ext.tex and giving api.tex
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	39 % XXX a really short intro only.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	40
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	41 \chapter{Introduction \label{intro}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	42
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	43 The Application Programmer's Interface to Python gives C and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	44 \Cpp{} programmers access to the Python interpreter at a variety of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	45 levels. The API is equally usable from \Cpp{}, but for brevity it is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	46 generally referred to as the Python/C API. There are two
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	47 fundamentally different reasons for using the Python/C API. The first
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	48 reason is to write \emph{extension modules} for specific purposes;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	49 these are C modules that extend the Python interpreter. This is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	50 probably the most common use. The second reason is to use Python as a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	51 component in a larger application; this technique is generally
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	52 referred to as \dfn{embedding} Python in an application.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	53
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	54 Writing an extension module is a relatively well-understood process,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	55 where a ``cookbook'' approach works well. There are several tools
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	56 that automate the process to some extent. While people have embedded
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	57 Python in other applications since its early existence, the process of
17875 151a2fa296fe Typo: "that" --> "than" Fred Drake <fdrake@acm.org> parents: 17835 diff changeset	58 embedding Python is less straightforward than writing an extension.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	59
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	60 Many API functions are useful independent of whether you're embedding
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	61 or extending Python; moreover, most applications that embed Python
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	62 will need to provide a custom extension as well, so it's probably a
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	63 good idea to become familiar with writing an extension before
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	64 attempting to embed Python in a real application.
1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	65
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	66
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	67 \section{Include Files \label{includes}}
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	68
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	69 All function, type and macro definitions needed to use the Python/C
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	70 API are included in your code by the following line:
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	71
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	72 \begin{verbatim}
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	73 #include "Python.h"
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	74 \end{verbatim}
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	75
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	76 This implies inclusion of the following standard headers:
14870 e35a3a772dca Note that including Python.h includes limits.h when available. Fred Drake <fdrake@acm.org> parents: 14782 diff changeset	77 \code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>},
e35a3a772dca Note that including Python.h includes limits.h when available. Fred Drake <fdrake@acm.org> parents: 14782 diff changeset	78 \code{<limits.h>}, and \code{<stdlib.h>} (if available).
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	79
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	80 All user visible names defined by Python.h (except those defined by
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	81 the included standard headers) have one of the prefixes \samp{Py} or
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	82 \samp{_Py}. Names beginning with \samp{_Py} are for internal use by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	83 the Python implementation and should not be used by extension writers.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	84 Structure member names do not have a reserved prefix.
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	85
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	86 \strong{Important:} user code should never define names that begin
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	87 with \samp{Py} or \samp{_Py}. This confuses the reader, and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	88 jeopardizes the portability of the user code to future Python
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	89 versions, which may define additional names beginning with one of
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	90 these prefixes.
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	91
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	92 The header files are typically installed with Python. On \UNIX, these
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	93 are located in the directories
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	94 \file{\envvar{prefix}/include/python\var{version}/} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	95 \file{\envvar{exec_prefix}/include/python\var{version}/}, where
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	96 \envvar{prefix} and \envvar{exec_prefix} are defined by the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	97 corresponding parameters to Python's \program{configure} script and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	98 \var{version} is \code{sys.version[:3]}. On Windows, the headers are
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	99 installed in \file{\envvar{prefix}/include}, where \envvar{prefix} is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	100 the installation directory specified to the installer.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	101
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	102 To include the headers, place both directories (if different) on your
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	103 compiler's search path for includes. Do \emph{not} place the parent
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	104 directories on the search path and then use
14557 a71385f8b4da Use \shortversion in a number of places. Fred Drake <fdrake@acm.org> parents: 14553 diff changeset	105 \samp{\#include <python\shortversion/Python.h>}; this will break on
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	106 multi-platform builds since the platform independent headers under
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	107 \envvar{prefix} include the platform specific headers from
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	108 \envvar{exec_prefix}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	109
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	110 \Cpp{} users should note that though the API is defined entirely using
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	111 C, the header files do properly declare the entry points to be
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	112 \code{extern "C"}, so there is no need to do anything special to use
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	113 the API from \Cpp.
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	114
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	115
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	116 \section{Objects, Types and Reference Counts \label{objects}}
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	117
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	118 Most Python/C API functions have one or more arguments as well as a
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	119 return value of type \ctype{PyObject*}. This type is a pointer
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	120 to an opaque data type representing an arbitrary Python
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	121 object. Since all Python object types are treated the same way by the
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	122 Python language in most situations (e.g., assignments, scope rules,
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	123 and argument passing), it is only fitting that they should be
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	124 represented by a single C type. Almost all Python objects live on the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	125 heap: you never declare an automatic or static variable of type
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	126 \ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	127 be declared. The sole exception are the type objects\obindex{type};
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	128 since these must never be deallocated, they are typically static
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	129 \ctype{PyTypeObject} objects.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	130
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	131 All Python objects (even Python integers) have a \dfn{type} and a
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	132 \dfn{reference count}. An object's type determines what kind of object
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	133 it is (e.g., an integer, a list, or a user-defined function; there are
11451 38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	134 many more as explained in the \citetitle[../ref/ref.html]{Python
38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	135 Reference Manual}). For each of the well-known types there is a macro
38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	136 to check whether an object is of that type; for instance,
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	137 \samp{PyList_Check(\var{a})} is true if (and only if) the object
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	138 pointed to by \var{a} is a Python list.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	139
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	140
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	141 \subsection{Reference Counts \label{refcounts}}
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	142
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	143 The reference count is important because today's computers have a
8029 95142c8a09c8 Typo: (and often severly limited) -- severely Fred Drake <fdrake@acm.org> parents: 8021 diff changeset	144 finite (and often severely limited) memory size; it counts how many
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	145 different places there are that have a reference to an object. Such a
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	146 place could be another object, or a global (or static) C variable, or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	147 a local variable in some C function. When an object's reference count
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	148 becomes zero, the object is deallocated. If it contains references to
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	149 other objects, their reference count is decremented. Those other
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	150 objects may be deallocated in turn, if this decrement makes their
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	151 reference count become zero, and so on. (There's an obvious problem
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	152 with objects that reference each other here; for now, the solution is
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	153 ``don't do that.'')
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	154
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	155 Reference counts are always manipulated explicitly. The normal way is
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	156 to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	157 increment an object's reference count by one, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	158 \cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	159 one. The \cfunction{Py_DECREF()} macro is considerably more complex
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	160 than the incref one, since it must check whether the reference count
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	161 becomes zero and then cause the object's deallocator to be called.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	162 The deallocator is a function pointer contained in the object's type
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	163 structure. The type-specific deallocator takes care of decrementing
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	164 the reference counts for other objects contained in the object if this
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	165 is a compound object type, such as a list, as well as performing any
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	166 additional finalization that's needed. There's no chance that the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	167 reference count can overflow; at least as many bits are used to hold
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	168 the reference count as there are distinct memory locations in virtual
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	169 memory (assuming \code{sizeof(long) >= sizeof(char*)}). Thus, the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	170 reference count increment is a simple operation.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	171
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	172 It is not necessary to increment an object's reference count for every
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	173 local variable that contains a pointer to an object. In theory, the
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	174 object's reference count goes up by one when the variable is made to
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	175 point to it and it goes down by one when the variable goes out of
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	176 scope. However, these two cancel each other out, so at the end the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	177 reference count hasn't changed. The only real reason to use the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	178 reference count is to prevent the object from being deallocated as
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	179 long as our variable is pointing to it. If we know that there is at
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	180 least one other reference to the object that lives at least as long as
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	181 our variable, there is no need to increment the reference count
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	182 temporarily. An important situation where this arises is in objects
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	183 that are passed as arguments to C functions in an extension module
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	184 that are called from Python; the call mechanism guarantees to hold a
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	185 reference to every argument for the duration of the call.
1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	186
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	187 However, a common pitfall is to extract an object from a list and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	188 hold on to it for a while without incrementing its reference count.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	189 Some other operation might conceivably remove the object from the
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	190 list, decrementing its reference count and possible deallocating it.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	191 The real danger is that innocent-looking operations may invoke
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	192 arbitrary Python code which could do this; there is a code path which
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	193 allows control to flow back to the user from a \cfunction{Py_DECREF()},
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	194 so almost any operation is potentially dangerous.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	195
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	196 A safe approach is to always use the generic operations (functions
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	197 whose name begins with \samp{PyObject_}, \samp{PyNumber_},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	198 \samp{PySequence_} or \samp{PyMapping_}). These operations always
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	199 increment the reference count of the object they return. This leaves
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	200 the caller with the responsibility to call
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	201 \cfunction{Py_DECREF()} when they are done with the result; this soon
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	202 becomes second nature.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	203
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	204
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	205 \subsubsection{Reference Count Details \label{refcountDetails}}
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	206
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	207 The reference count behavior of functions in the Python/C API is best
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	208 explained in terms of \emph{ownership of references}. Note that we
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	209 talk of owning references, never of owning objects; objects are always
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	210 shared! When a function owns a reference, it has to dispose of it
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	211 properly --- either by passing ownership on (usually to its caller) or
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	212 by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	213 a function passes ownership of a reference on to its caller, the
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	214 caller is said to receive a \emph{new} reference. When no ownership
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	215 is transferred, the caller is said to \emph{borrow} the reference.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	216 Nothing needs to be done for a borrowed reference.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	217
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	218 Conversely, when a calling function passes it a reference to an
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	219 object, there are two possibilities: the function \emph{steals} a
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	220 reference to the object, or it does not. Few functions steal
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	221 references; the two notable exceptions are
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	222 \cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	223 \cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	224 steal a reference to the item (but not to the tuple or list into which
8029 95142c8a09c8 Typo: (and often severly limited) -- severely Fred Drake <fdrake@acm.org> parents: 8021 diff changeset	225 the item is put!). These functions were designed to steal a reference
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	226 because of a common idiom for populating a tuple or list with newly
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	227 created objects; for example, the code to create the tuple \code{(1,
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	228 2, "three")} could look like this (forgetting about error handling for
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	229 the moment; a better way to code this is shown below):
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	230
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	231 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	232 PyObject *t;
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	233
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	234 t = PyTuple_New(3);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	235 PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	236 PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	237 PyTuple_SetItem(t, 2, PyString_FromString("three"));
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	238 \end{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	239
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	240 Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	241 set tuple items; \cfunction{PySequence_SetItem()} and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	242 \cfunction{PyObject_SetItem()} refuse to do this since tuples are an
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	243 immutable data type. You should only use
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	244 \cfunction{PyTuple_SetItem()} for tuples that you are creating
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	245 yourself.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	246
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	247 Equivalent code for populating a list can be written using
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	248 \cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	249 can also use \cfunction{PySequence_SetItem()}; this illustrates the
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	250 difference between the two (the extra \cfunction{Py_DECREF()} calls):
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	251
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	252 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	253 PyObject l, x;
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	254
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	255 l = PyList_New(3);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	256 x = PyInt_FromLong(1L);
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	257 PySequence_SetItem(l, 0, x); Py_DECREF(x);
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	258 x = PyInt_FromLong(2L);
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	259 PySequence_SetItem(l, 1, x); Py_DECREF(x);
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	260 x = PyString_FromString("three");
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	261 PySequence_SetItem(l, 2, x); Py_DECREF(x);
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	262 \end{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	263
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	264 You might find it strange that the ``recommended'' approach takes more
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	265 code. However, in practice, you will rarely use these ways of
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	266 creating and populating a tuple or list. There's a generic function,
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	267 \cfunction{Py_BuildValue()}, that can create most common objects from
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	268 C values, directed by a \dfn{format string}. For example, the
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	269 above two blocks of code could be replaced by the following (which
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	270 also takes care of the error checking):
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	271
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	272 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	273 PyObject t, l;
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	274
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	275 t = Py_BuildValue("(iis)", 1, 2, "three");
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	276 l = Py_BuildValue("[iis]", 1, 2, "three");
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	277 \end{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	278
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	279 It is much more common to use \cfunction{PyObject_SetItem()} and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	280 friends with items whose references you are only borrowing, like
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	281 arguments that were passed in to the function you are writing. In
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	282 that case, their behaviour regarding reference counts is much saner,
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	283 since you don't have to increment a reference count so you can give a
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	284 reference away (``have it be stolen''). For example, this function
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	285 sets all items of a list (actually, any mutable sequence) to a given
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	286 item:
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	287
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	288 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	289 int set_all(PyObject target, PyObject item)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	290 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	291 int i, n;
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	292
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	293 n = PyObject_Length(target);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	294 if (n < 0)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	295 return -1;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	296 for (i = 0; i < n; i++) {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	297 if (PyObject_SetItem(target, i, item) < 0)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	298 return -1;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	299 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	300 return 0;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	301 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	302 \end{verbatim}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	303 \ttindex{set_all()}
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	304
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	305 The situation is slightly different for function return values.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	306 While passing a reference to most functions does not change your
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	307 ownership responsibilities for that reference, many functions that
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	308 return a referece to an object give you ownership of the reference.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	309 The reason is simple: in many cases, the returned object is created
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	310 on the fly, and the reference you get is the only reference to the
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	311 object. Therefore, the generic functions that return object
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	312 references, like \cfunction{PyObject_GetItem()} and
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	313 \cfunction{PySequence_GetItem()}, always return a new reference (the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	314 caller becomes the owner of the reference).
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	315
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	316 It is important to realize that whether you own a reference returned
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	317 by a function depends on which function you call only --- \emph{the
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	318 plumage} (the type of the type of the object passed as an
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	319 argument to the function) \emph{doesn't enter into it!} Thus, if you
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	320 extract an item from a list using \cfunction{PyList_GetItem()}, you
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	321 don't own the reference --- but if you obtain the same item from the
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	322 same list using \cfunction{PySequence_GetItem()} (which happens to
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	323 take exactly the same arguments), you do own a reference to the
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	324 returned object.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	325
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	326 Here is an example of how you could write a function that computes the
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	327 sum of the items in a list of integers; once using
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	328 \cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	329 \cfunction{PySequence_GetItem()}\ttindex{PySequence_GetItem()}.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	330
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	331 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	332 long sum_list(PyObject *list)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	333 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	334 int i, n;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	335 long total = 0;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	336 PyObject *item;
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	337
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	338 n = PyList_Size(list);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	339 if (n < 0)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	340 return -1; /* Not a list */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	341 for (i = 0; i < n; i++) {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	342 item = PyList_GetItem(list, i); /* Can't fail */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	343 if (!PyInt_Check(item)) continue; /* Skip non-integers */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	344 total += PyInt_AsLong(item);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	345 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	346 return total;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	347 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	348 \end{verbatim}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	349 \ttindex{sum_list()}
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	350
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	351 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	352 long sum_sequence(PyObject *sequence)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	353 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	354 int i, n;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	355 long total = 0;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	356 PyObject *item;
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	357 n = PySequence_Length(sequence);
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	358 if (n < 0)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	359 return -1; /* Has no length */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	360 for (i = 0; i < n; i++) {
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	361 item = PySequence_GetItem(sequence, i);
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	362 if (item == NULL)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	363 return -1; /* Not a sequence, or other failure */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	364 if (PyInt_Check(item))
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	365 total += PyInt_AsLong(item);
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	366 Py_DECREF(item); /* Discard reference ownership */
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	367 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	368 return total;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	369 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	370 \end{verbatim}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	371 \ttindex{sum_sequence()}
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	372
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	373
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	374 \subsection{Types \label{types}}
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	375
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	376 There are few other data types that play a significant role in
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	377 the Python/C API; most are simple C types such as \ctype{int},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	378 \ctype{long}, \ctype{double} and \ctype{char*}. A few structure types
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	379 are used to describe static tables used to list the functions exported
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	380 by a module or the data attributes of a new object type, and another
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	381 is used to describe the value of a complex number. These will
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	382 be discussed together with the functions that use them.
1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	383
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	384
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	385 \section{Exceptions \label{exceptions}}
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	386
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	387 The Python programmer only needs to deal with exceptions if specific
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	388 error handling is required; unhandled exceptions are automatically
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	389 propagated to the caller, then to the caller's caller, and so on, until
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	390 they reach the top-level interpreter, where they are reported to the
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	391 user accompanied by a stack traceback.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	392
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	393 For C programmers, however, error checking always has to be explicit.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	394 All functions in the Python/C API can raise exceptions, unless an
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	395 explicit claim is made otherwise in a function's documentation. In
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	396 general, when a function encounters an error, it sets an exception,
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	397 discards any object references that it owns, and returns an
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	398 error indicator --- usually \NULL{} or \code{-1}. A few functions
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	399 return a Boolean true/false result, with false indicating an error.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	400 Very few functions return no explicit error indicator or have an
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	401 ambiguous return value, and require explicit testing for errors with
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	402 \cfunction{PyErr_Occurred()}\ttindex{PyErr_Occurred()}.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	403
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	404 Exception state is maintained in per-thread storage (this is
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	405 equivalent to using global storage in an unthreaded application). A
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	406 thread can be in one of two states: an exception has occurred, or not.
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	407 The function \cfunction{PyErr_Occurred()} can be used to check for
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	408 this: it returns a borrowed reference to the exception type object
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	409 when an exception has occurred, and \NULL{} otherwise. There are a
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	410 number of functions to set the exception state:
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	411 \cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	412 common (though not the most general) function to set the exception
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	413 state, and \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} clears the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	414 exception state.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	415
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	416 The full exception state consists of three objects (all of which can
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	417 be \NULL{}): the exception type, the corresponding exception
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	418 value, and the traceback. These have the same meanings as the Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	419 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	420 \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	421 objects \code{sys.exc_type}, \code{sys.exc_value}, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	422 \code{sys.exc_traceback}; however, they are not the same: the Python
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	423 objects represent the last exception being handled by a Python
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	424 \keyword{try} \ldots\ \keyword{except} statement, while the C level
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	425 exception state only exists while an exception is being passed on
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	426 between C functions until it reaches the Python bytecode interpreter's
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	427 main loop, which takes care of transferring it to \code{sys.exc_type}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	428 and friends.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	429
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	430 Note that starting with Python 1.5, the preferred, thread-safe way to
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	431 access the exception state from Python code is to call the function
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	432 \withsubitem{(in module sys)}{\ttindex{exc_info()}}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	433 \function{sys.exc_info()}, which returns the per-thread exception state
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	434 for Python code. Also, the semantics of both ways to access the
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	435 exception state have changed so that a function which catches an
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	436 exception will save and restore its thread's exception state so as to
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	437 preserve the exception state of its caller. This prevents common bugs
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	438 in exception handling code caused by an innocent-looking function
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	439 overwriting the exception being handled; it also reduces the often
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	440 unwanted lifetime extension for objects that are referenced by the
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	441 stack frames in the traceback.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	442
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	443 As a general principle, a function that calls another function to
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	444 perform some task should check whether the called function raised an
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	445 exception, and if so, pass the exception state on to its caller. It
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	446 should discard any object references that it owns, and return an
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	447 error indicator, but it should \emph{not} set another exception ---
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	448 that would overwrite the exception that was just raised, and lose
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	449 important information about the exact cause of the error.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	450
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	451 A simple example of detecting exceptions and passing them on is shown
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	452 in the \cfunction{sum_sequence()}\ttindex{sum_sequence()} example
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	453 above. It so happens that that example doesn't need to clean up any
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	454 owned references when it detects an error. The following example
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	455 function shows some error cleanup. First, to remind you why you like
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	456 Python, we show the equivalent Python code:
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	457
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	458 \begin{verbatim}
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	459 def incr_item(dict, key):
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	460 try:
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	461 item = dict[key]
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	462 except KeyError:
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	463 item = 0
15453 7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	464 dict[key] = item + 1
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	465 \end{verbatim}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	466 \ttindex{incr_item()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	467
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	468 Here is the corresponding C code, in all its glory:
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	469
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	470 \begin{verbatim}
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	471 int incr_item(PyObject dict, PyObject key)
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	472 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	473 /* Objects all initialized to NULL for Py_XDECREF */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	474 PyObject item = NULL, const_one = NULL, *incremented_item = NULL;
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	475 int rv = -1; /* Return value initialized to -1 (failure) */
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	476
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	477 item = PyObject_GetItem(dict, key);
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	478 if (item == NULL) {
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	479 /* Handle KeyError only: */
15453 7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	480 if (!PyErr_ExceptionMatches(PyExc_KeyError))
7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	481 goto error;
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	482
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	483 /* Clear the error and use zero: */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	484 PyErr_Clear();
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	485 item = PyInt_FromLong(0L);
15453 7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	486 if (item == NULL)
7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	487 goto error;
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	488 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	489 const_one = PyInt_FromLong(1L);
15453 7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	490 if (const_one == NULL)
7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	491 goto error;
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	492
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	493 incremented_item = PyNumber_Add(item, const_one);
15453 7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	494 if (incremented_item == NULL)
7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	495 goto error;
7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	496
7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	497 if (PyObject_SetItem(dict, key, incremented_item) < 0)
7721fb509462 In the first discussion showing how to handle exceptions from C, make the Fred Drake <fdrake@acm.org> parents: 15444 diff changeset	498 goto error;
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	499 rv = 0; /* Success */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	500 /* Continue with cleanup code */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	501
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	502 error:
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	503 /* Cleanup code, shared by success and failure path */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	504
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	505 /* Use Py_XDECREF() to ignore NULL references */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	506 Py_XDECREF(item);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	507 Py_XDECREF(const_one);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	508 Py_XDECREF(incremented_item);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	509
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	510 return rv; /* -1 for error, 0 for success */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	511 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	512 \end{verbatim}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	513 \ttindex{incr_item()}
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	514
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	515 This example represents an endorsed use of the \keyword{goto} statement
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	516 in C! It illustrates the use of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	517 \cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	518 \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	519 handle specific exceptions, and the use of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	520 \cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	521 dispose of owned references that may be \NULL{} (note the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	522 \character{X} in the name; \cfunction{Py_DECREF()} would crash when
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	523 confronted with a \NULL{} reference). It is important that the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	524 variables used to hold owned references are initialized to \NULL{} for
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	525 this to work; likewise, the proposed return value is initialized to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	526 \code{-1} (failure) and only set to success after the final call made
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	527 is successful.
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	528
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	529
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	530 \section{Embedding Python \label{embedding}}
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	531
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	532 The one important task that only embedders (as opposed to extension
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	533 writers) of the Python interpreter have to worry about is the
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	534 initialization, and possibly the finalization, of the Python
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	535 interpreter. Most functionality of the interpreter can only be used
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	536 after the interpreter has been initialized.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	537
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	538 The basic initialization function is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	539 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	540 This initializes the table of loaded modules, and creates the
7310 6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	541 fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
19242 d99c1240d0ac Add "exceptions" to the list of fundamental modules Fred Drake <fdrake@acm.org> parents: 19156 diff changeset	542 \module{__main__}\refbimodindex{__main__}, \module{sys}\refbimodindex{sys},
d99c1240d0ac Add "exceptions" to the list of fundamental modules Fred Drake <fdrake@acm.org> parents: 19156 diff changeset	543 and \module{exceptions}.\refbimodindex{exceptions} It also initializes
d99c1240d0ac Add "exceptions" to the list of fundamental modules Fred Drake <fdrake@acm.org> parents: 19156 diff changeset	544 the module search path (\code{sys.path}).%
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	545 \indexiii{module}{search}{path}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	546 \withsubitem{(in module sys)}{\ttindex{path}}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	547
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	548 \cfunction{Py_Initialize()} does not set the ``script argument list''
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	549 (\code{sys.argv}). If this variable is needed by Python code that
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	550 will be executed later, it must be set explicitly with a call to
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	551 \code{PySys_SetArgv(\var{argc},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	552 \var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	553 \cfunction{Py_Initialize()}.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	554
7081 0baa2ab42ee9 Consistency: Fred Drake <fdrake@acm.org> parents: 7071 diff changeset	555 On most systems (in particular, on \UNIX{} and Windows, although the
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	556 details are slightly different),
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	557 \cfunction{Py_Initialize()} calculates the module search path based
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	558 upon its best guess for the location of the standard Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	559 interpreter executable, assuming that the Python library is found in a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	560 fixed location relative to the Python interpreter executable. In
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	561 particular, it looks for a directory named
14557 a71385f8b4da Use \shortversion in a number of places. Fred Drake <fdrake@acm.org> parents: 14553 diff changeset	562 \file{lib/python\shortversion} relative to the parent directory where
a71385f8b4da Use \shortversion in a number of places. Fred Drake <fdrake@acm.org> parents: 14553 diff changeset	563 the executable named \file{python} is found on the shell command
a71385f8b4da Use \shortversion in a number of places. Fred Drake <fdrake@acm.org> parents: 14553 diff changeset	564 search path (the environment variable \envvar{PATH}).
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	565
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	566 For instance, if the Python executable is found in
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	567 \file{/usr/local/bin/python}, it will assume that the libraries are in
14557 a71385f8b4da Use \shortversion in a number of places. Fred Drake <fdrake@acm.org> parents: 14553 diff changeset	568 \file{/usr/local/lib/python\shortversion}. (In fact, this particular path
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	569 is also the ``fallback'' location, used when no executable file named
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	570 \file{python} is found along \envvar{PATH}.) The user can override
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	571 this behavior by setting the environment variable \envvar{PYTHONHOME},
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	572 or insert additional directories in front of the standard path by
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	573 setting \envvar{PYTHONPATH}.
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	574
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	575 The embedding application can steer the search by calling
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	576 \code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	577 \cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	578 overrides this and \envvar{PYTHONPATH} is still inserted in front of
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	579 the standard path. An application that requires total control has to
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	580 provide its own implementation of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	581 \cfunction{Py_GetPath()}\ttindex{Py_GetPath()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	582 \cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	583 \cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	584 \cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	585 defined in \file{Modules/getpath.c}).
6040 1a43699108a6 Added new intro sections (incomplete); fixed various typos Guido van Rossum <guido@python.org> parents: 5588 diff changeset	586
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	587 Sometimes, it is desirable to ``uninitialize'' Python. For instance,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	588 the application may want to start over (make another call to
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	589 \cfunction{Py_Initialize()}) or the application is simply done with its
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	590 use of Python and wants to free all memory allocated by Python. This
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	591 can be accomplished by calling \cfunction{Py_Finalize()}. The function
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	592 \cfunction{Py_IsInitialized()}\ttindex{Py_IsInitialized()} returns
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	593 true if Python is currently in the initialized state. More
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	594 information about these functions is given in a later chapter.
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	595
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	596
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	597 \chapter{The Very High Level Layer \label{veryhigh}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	598
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	599 The functions in this chapter will let you execute Python source code
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	600 given in a file or a buffer, but they will not let you interact in a
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	601 more detailed way with the interpreter.
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	602
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	603 Several of these functions accept a start symbol from the grammar as a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	604 parameter. The available start symbols are \constant{Py_eval_input},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	605 \constant{Py_file_input}, and \constant{Py_single_input}. These are
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	606 described following the functions which accept them as parameters.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	607
13959 8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up Fred Drake <fdrake@acm.org> parents: 13929 diff changeset	608 Note also that several of these functions take \ctype{FILE*}
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up Fred Drake <fdrake@acm.org> parents: 13929 diff changeset	609 parameters. On particular issue which needs to be handled carefully
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up Fred Drake <fdrake@acm.org> parents: 13929 diff changeset	610 is that the \ctype{FILE} structure for different C libraries can be
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up Fred Drake <fdrake@acm.org> parents: 13929 diff changeset	611 different and incompatible. Under Windows (at least), it is possible
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up Fred Drake <fdrake@acm.org> parents: 13929 diff changeset	612 for dynamically linked extensions to actually use different libraries,
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up Fred Drake <fdrake@acm.org> parents: 13929 diff changeset	613 so care should be taken that \ctype{FILE*} parameters are only passed
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up Fred Drake <fdrake@acm.org> parents: 13929 diff changeset	614 to these functions if it is certain that they were created by the same
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up Fred Drake <fdrake@acm.org> parents: 13929 diff changeset	615 library that the Python runtime is using.
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up Fred Drake <fdrake@acm.org> parents: 13929 diff changeset	616
17877 13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	617 \begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	618 The main program for the standard interpreter. This is made
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	619 available for programs which embed Python. The \var{argc} and
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	620 \var{argv} parameters should be prepared exactly as those which are
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	621 passed to a C program's \cfunction{main()} function. It is
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	622 important to note that the argument list may be modified (but the
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	623 contents of the strings pointed to by the argument list are not).
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	624 The return value will be the integer passed to the
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	625 \function{sys.exit()} function, \code{1} if the interpreter exits
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	626 due to an exception, or \code{2} if the parameter list does not
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	627 represent a valid Python command line.
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	628 \end{cfuncdesc}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	629
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	630 \begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE fp, char filename}
10786 a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	631 If \var{fp} refers to a file associated with an interactive device
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	632 (console or terminal input or \UNIX{} pseudo-terminal), return the
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	633 value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	634 result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is
13929 f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	635 \NULL{}, this function uses \code{"???"} as the filename.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	636 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	637
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	638 \begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
10786 a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	639 Executes the Python source code from \var{command} in the
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	640 \module{__main__} module. If \module{__main__} does not already
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	641 exist, it is created. Returns \code{0} on success or \code{-1} if
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	642 an exception was raised. If there was an error, there is no way to
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	643 get the exception information.
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	644 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	645
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	646 \begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE fp, char filename}
10786 a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	647 Similar to \cfunction{PyRun_SimpleString()}, but the Python source
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	648 code is read from \var{fp} instead of an in-memory string.
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	649 \var{filename} should be the name of the file.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	650 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	651
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	652 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE fp, char filename}
13929 f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	653 Read and execute a single statement from a file associated with an
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	654 interactive device. If \var{filename} is \NULL, \code{"???"} is
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	655 used instead. The user will be prompted using \code{sys.ps1} and
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	656 \code{sys.ps2}. Returns \code{0} when the input was executed
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	657 successfully, \code{-1} if there was an exception, or an error code
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	658 from the \file{errcode.h} include file distributed as part of Python
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	659 in case of a parse error. (Note that \file{errcode.h} is not
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	660 included by \file{Python.h}, so must be included specifically if
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	661 needed.)
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	662 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	663
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	664 \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE fp, char filename}
13929 f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	665 Read and execute statements from a file associated with an
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	666 interactive device until \EOF{} is reached. If \var{filename} is
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	667 \NULL, \code{"???"} is used instead. The user will be prompted
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	668 using \code{sys.ps1} and \code{sys.ps2}. Returns \code{0} at \EOF.
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	669 \end{cfuncdesc}
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	670
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	671 \begin{cfuncdesc}{struct _node}{PyParser_SimpleParseString}{char str,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	672 int start}
10786 a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	673 Parse Python source code from \var{str} using the start token
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	674 \var{start}. The result can be used to create a code object which
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	675 can be evaluated efficiently. This is useful if a code fragment
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	676 must be evaluated many times.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	677 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	678
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	679 \begin{cfuncdesc}{struct _node}{PyParser_SimpleParseFile}{FILE fp,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	680 char *filename, int start}
10786 a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	681 Similar to \cfunction{PyParser_SimpleParseString()}, but the Python
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	682 source code is read from \var{fp} instead of an in-memory string.
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	683 \var{filename} should be the name of the file.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	684 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	685
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	686 \begin{cfuncdesc}{PyObject}{PyRun_String}{char str, int start,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	687 PyObject *globals,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	688 PyObject *locals}
10786 a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	689 Execute Python source code from \var{str} in the context specified
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	690 by the dictionaries \var{globals} and \var{locals}. The parameter
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	691 \var{start} specifies the start token that should be used to parse
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	692 the source code.
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	693
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	694 Returns the result of executing the code as a Python object, or
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	695 \NULL{} if an exception was raised.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	696 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	697
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	698 \begin{cfuncdesc}{PyObject}{PyRun_File}{FILE fp, char *filename,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	699 int start, PyObject *globals,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	700 PyObject *locals}
10786 a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	701 Similar to \cfunction{PyRun_String()}, but the Python source code is
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	702 read from \var{fp} instead of an in-memory string.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	703 \var{filename} should be the name of the file.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	704 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	705
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	706 \begin{cfuncdesc}{PyObject}{Py_CompileString}{char str, char *filename,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	707 int start}
10786 a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	708 Parse and compile the Python source code in \var{str}, returning the
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter. Fred Drake <fdrake@acm.org> parents: 10219 diff changeset	709 resulting code object. The start token is given by \var{start};
11222 ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	710 this can be used to constrain the code which can be compiled and should
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	711 be \constant{Py_eval_input}, \constant{Py_file_input}, or
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	712 \constant{Py_single_input}. The filename specified by
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	713 \var{filename} is used to construct the code object and may appear
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	714 in tracebacks or \exception{SyntaxError} exception messages. This
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	715 returns \NULL{} if the code cannot be parsed or compiled.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	716 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	717
11222 ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	718 \begin{cvardesc}{int}{Py_eval_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	719 The start symbol from the Python grammar for isolated expressions;
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	720 for use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
11222 ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	721 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	722
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	723 \begin{cvardesc}{int}{Py_file_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	724 The start symbol from the Python grammar for sequences of statements
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	725 as read from a file or other source; for use with
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	726 \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. This is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	727 the symbol to use when compiling arbitrarily long Python source code.
11222 ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	728 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	729
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	730 \begin{cvardesc}{int}{Py_single_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	731 The start symbol from the Python grammar for a single statement; for
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	732 use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	733 This is the symbol used for the interactive interpreter loop.
11222 ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	734 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented Fred Drake <fdrake@acm.org> parents: 11176 diff changeset	735
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	736
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	737 \chapter{Reference Counting \label{countingRefs}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	738
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	739 The macros in this section are used for managing reference counts
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	740 of Python objects.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	741
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	742 \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	743 Increment the reference count for object \var{o}. The object must
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	744 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	745 \cfunction{Py_XINCREF()}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	746 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	747
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	748 \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	749 Increment the reference count for object \var{o}. The object may be
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	750 \NULL{}, in which case the macro has no effect.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	751 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	752
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	753 \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	754 Decrement the reference count for object \var{o}. The object must
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	755 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	756 \cfunction{Py_XDECREF()}. If the reference count reaches zero, the
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	757 object's type's deallocation function (which must not be \NULL{}) is
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	758 invoked.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	759
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	760 \strong{Warning:} The deallocation function can cause arbitrary Python
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	761 code to be invoked (e.g. when a class instance with a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	762 \method{__del__()} method is deallocated). While exceptions in such
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	763 code are not propagated, the executed code has free access to all
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	764 Python global variables. This means that any object that is reachable
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	765 from a global variable should be in a consistent state before
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	766 \cfunction{Py_DECREF()} is invoked. For example, code to delete an
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	767 object from a list should copy a reference to the deleted object in a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	768 temporary variable, update the list data structure, and then call
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	769 \cfunction{Py_DECREF()} for the temporary variable.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	770 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	771
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	772 \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	773 Decrement the reference count for object \var{o}. The object may be
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	774 \NULL{}, in which case the macro has no effect; otherwise the effect
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	775 is the same as for \cfunction{Py_DECREF()}, and the same warning
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	776 applies.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	777 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	778
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	779 The following functions or macros are only for use within the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	780 interpreter core: \cfunction{_Py_Dealloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	781 \cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	782 well as the global variable \cdata{_Py_RefTotal}.
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	783
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	784
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	785 \chapter{Exception Handling \label{exceptionHandling}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	786
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	787 The functions described in this chapter will let you handle and raise Python
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	788 exceptions. It is important to understand some of the basics of
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	789 Python exception handling. It works somewhat like the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	790 \UNIX{} \cdata{errno} variable: there is a global indicator (per
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	791 thread) of the last error that occurred. Most functions don't clear
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	792 this on success, but will set it to indicate the cause of the error on
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	793 failure. Most functions also return an error indicator, usually
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	794 \NULL{} if they are supposed to return a pointer, or \code{-1} if they
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	795 return an integer (exception: the \cfunction{PyArg_Parse*()} functions
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	796 return \code{1} for success and \code{0} for failure). When a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	797 function must fail because some function it called failed, it
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	798 generally doesn't set the error indicator; the function it called
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	799 already set it.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	800
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	801 The error indicator consists of three Python objects corresponding to
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	802 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	803 \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	804 the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	805 \code{sys.exc_traceback}. API functions exist to interact with the
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	806 error indicator in various ways. There is a separate error indicator
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	807 for each thread.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	808
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	809 % XXX Order of these should be more thoughtful.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	810 % Either alphabetical or some kind of structure.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	811
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	812 \begin{cfuncdesc}{void}{PyErr_Print}{}
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	813 Print a standard traceback to \code{sys.stderr} and clear the error
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	814 indicator. Call this function only when the error indicator is set.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	815 (Otherwise it will cause a fatal error!)
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	816 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	817
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	818 \begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{}
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	819 Test whether the error indicator is set. If set, return the exception
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	820 \emph{type} (the first argument to the last call to one of the
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	821 \cfunction{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}). If
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	822 not set, return \NULL{}. You do not own a reference to the return
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	823 value, so you do not need to \cfunction{Py_DECREF()} it.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	824 \strong{Note:} Do not compare the return value to a specific
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	825 exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	826 below. (The comparison could easily fail since the exception may be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	827 an instance instead of a class, in the case of a class exception, or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	828 it may the a subclass of the expected exception.)
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	829 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	830
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	831 \begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	832 Equivalent to
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	833 \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	834 This should only be called when an exception is actually set; a memory
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	835 access violation will occur if no exception has been raised.
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	836 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	837
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	838 \begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject given, PyObject exc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	839 Return true if the \var{given} exception matches the exception in
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	840 \var{exc}. If \var{exc} is a class object, this also returns true
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	841 when \var{given} is an instance of a subclass. If \var{exc} is a tuple, all
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	842 exceptions in the tuple (and recursively in subtuples) are searched
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	843 for a match. If \var{given} is \NULL, a memory access violation will
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	844 occur.
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	845 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	846
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	847 \begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObjectexc, PyObjectval, PyObject**tb}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	848 Under certain circumstances, the values returned by
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	849 \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	850 \code{\var{exc}} is a class object but \code{\var{val}} is not an
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	851 instance of the same class. This function can be used to instantiate
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	852 the class in that case. If the values are already normalized, nothing
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	853 happens. The delayed normalization is implemented to improve
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	854 performance.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	855 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	856
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	857 \begin{cfuncdesc}{void}{PyErr_Clear}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	858 Clear the error indicator. If the error indicator is not set, there
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	859 is no effect.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	860 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	861
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	862 \begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject ptype, PyObject pvalue,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	863 PyObject **ptraceback}
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	864 Retrieve the error indicator into three variables whose addresses are
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	865 passed. If the error indicator is not set, set all three variables to
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	866 \NULL{}. If it is set, it will be cleared and you own a reference to
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	867 each object retrieved. The value and traceback object may be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	868 \NULL{} even when the type object is not. \strong{Note:} This
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	869 function is normally only used by code that needs to handle exceptions
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	870 or by code that needs to save and restore the error indicator
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	871 temporarily.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	872 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	873
14279 b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	874 \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject type, PyObject value,
b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	875 PyObject *traceback}
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	876 Set the error indicator from the three objects. If the error
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	877 indicator is already set, it is cleared first. If the objects are
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	878 \NULL{}, the error indicator is cleared. Do not pass a \NULL{} type
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	879 and non-\NULL{} value or traceback. The exception type should be a
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	880 string or class; if it is a class, the value should be an instance of
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	881 that class. Do not pass an invalid exception type or value.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	882 (Violating these rules will cause subtle problems later.) This call
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	883 takes away a reference to each object: you must own a reference
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	884 to each object before the call and after the call you no longer own
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	885 these references. (If you don't understand this, don't use this
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	886 function. I warned you.) \strong{Note:} This function is normally
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	887 only used by code that needs to save and restore the error indicator
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	888 temporarily.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	889 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	890
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	891 \begin{cfuncdesc}{void}{PyErr_SetString}{PyObject type, char message}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	892 This is the most common way to set the error indicator. The first
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	893 argument specifies the exception type; it is normally one of the
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	894 standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	895 increment its reference count. The second argument is an error
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	896 message; it is converted to a string object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	897 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	898
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	899 \begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject type, PyObject value}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	900 This function is similar to \cfunction{PyErr_SetString()} but lets you
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	901 specify an arbitrary Python object for the ``value'' of the exception.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	902 You need not increment its reference count.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	903 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	904
12355 04802b7e8a1f Yet another markup nit: functions that are part of the Python/C API Fred Drake <fdrake@acm.org> parents: 12354 diff changeset	905 \begin{cfuncdesc}{PyObject}{PyErr_Format}{PyObject exception,
14347 2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	906 const char *format, \moreargs}
15236 f1ade8ab1869 For PyErr_Format(), note that the exception parameter can be a string or Fred Drake <fdrake@acm.org> parents: 15087 diff changeset	907 This function sets the error indicator. \var{exception} should be a
f1ade8ab1869 For PyErr_Format(), note that the exception parameter can be a string or Fred Drake <fdrake@acm.org> parents: 15087 diff changeset	908 Python exception (string or class, not an instance).
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	909 \var{format} should be a string, containing format codes, similar to
14347 2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	910 \cfunction{printf}. The \code{width.precision} before a format code
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	911 is parsed, but the width part is ignored.
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	912
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	913 \begin{tableii}{c\|l}{character}{Character}{Meaning}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	914 \lineii{c}{Character, as an \ctype{int} parameter}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	915 \lineii{d}{Number in decimal, as an \ctype{int} parameter}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	916 \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	917 \lineii{x}{A string, as a \ctype{char *} parameter}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	918 \end{tableii}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	919
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	920 An unrecognized format character causes all the rest of
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	921 the format string to be copied as-is to the result string,
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	922 and any extra arguments discarded.
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	923
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed. Moshe Zadka <moshez@math.huji.ac.il> parents: 14337 diff changeset	924 A new reference is returned, which is owned by the caller.
12353 54e80db49423 document PyErr_Format Jeremy Hylton <jeremy@alum.mit.edu> parents: 12258 diff changeset	925 \end{cfuncdesc}
54e80db49423 document PyErr_Format Jeremy Hylton <jeremy@alum.mit.edu> parents: 12258 diff changeset	926
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	927 \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	928 This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	929 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	930
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	931 \begin{cfuncdesc}{int}{PyErr_BadArgument}{}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	932 This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	933 \var{message})}, where \var{message} indicates that a built-in operation
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	934 was invoked with an illegal argument. It is mostly for internal use.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	935 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	936
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	937 \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	938 This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	939 returns \NULL{} so an object allocation function can write
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	940 \samp{return PyErr_NoMemory();} when it runs out of memory.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	941 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	942
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	943 \begin{cfuncdesc}{PyObject}{PyErr_SetFromErrno}{PyObject type}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	944 This is a convenience function to raise an exception when a C library
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	945 function has returned an error and set the C variable \cdata{errno}.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	946 It constructs a tuple object whose first item is the integer
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	947 \cdata{errno} value and whose second item is the corresponding error
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	948 message (gotten from \cfunction{strerror()}\ttindex{strerror()}), and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	949 then calls
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	950 \samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	951 the \cdata{errno} value is \constant{EINTR}, indicating an interrupted
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	952 system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	953 the error indicator, leaves it set to that. The function always
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	954 returns \NULL{}, so a wrapper function around a system call can write
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	955 \samp{return PyErr_SetFromErrno();} when the system call returns an
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	956 error.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	957 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	958
18192 19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	959 \begin{cfuncdesc}{PyObject}{PyErr_SetFromErrnoWithFilename}{PyObject type,
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	960 char *filename}
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	961 Similar to \cfunction{PyErr_SetFromErrno()}, with the additional
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	962 behavior that if \var{filename} is not \NULL, it is passed to the
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	963 constructor of \var{type} as a third parameter. In the case of
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	964 exceptions such as \exception{IOError} and \exception{OSError}, this
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	965 is used to define the \member{filename} attribute of the exception
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	966 instance.
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	967 \end{cfuncdesc}
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	968
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	969 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	970 This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	971 \var{message})}, where \var{message} indicates that an internal
6084 0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new Guido van Rossum <guido@python.org> parents: 6074 diff changeset	972 operation (e.g. a Python/C API function) was invoked with an illegal
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	973 argument. It is mostly for internal use.
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	974 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	975
15613 35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	976 \begin{cfuncdesc}{int}{PyErr_Warn}{PyObject category, char message}
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	977 Issue a warning message. The \var{category} argument is a warning
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	978 category (see below) or \NULL; the \var{message} argument is a message
15613 35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	979 string.
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	980
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	981 This function normally prints a warning message to \var{sys.stderr};
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	982 however, it is also possible that the user has specified that warnings
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	983 are to be turned into errors, and in that case this will raise an
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	984 exception. It is also possible that the function raises an exception
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	985 because of a problem with the warning machinery (the implementation
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	986 imports the \module{warnings} module to do the heavy lifting). The
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	987 return value is \code{0} if no exception is raised, or \code{-1} if
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	988 an exception is raised. (It is not possible to determine whether a
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	989 warning message is actually printed, nor what the reason is for the
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	990 exception; this is intentional.) If an exception is raised, the
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	991 caller should do its normal exception handling
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	992 (e.g. \cfunction{Py_DECREF()} owned references and return an error
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	993 value).
15613 35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	994
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	995 Warning categories must be subclasses of \cdata{Warning}; the default
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	996 warning category is \cdata{RuntimeWarning}. The standard Python
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	997 warning categories are available as global variables whose names are
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	998 \samp{PyExc_} followed by the Python exception name. These have the
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	999 type \ctype{PyObject*}; they are all class objects. Their names are
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	1000 \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	1001 \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	1002 \cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass of
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	1003 \cdata{PyExc_Exception}; the other warning categories are subclasses
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	1004 of \cdata{PyExc_Warning}.
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	1005
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	1006 For information about warning control, see the documentation for the
15733 00c6855d742a Markup nit: Command line options should be marked with \programopt. Fred Drake <fdrake@acm.org> parents: 15613 diff changeset	1007 \module{warnings} module and the \programopt{-W} option in the command
00c6855d742a Markup nit: Command line options should be marked with \programopt. Fred Drake <fdrake@acm.org> parents: 15613 diff changeset	1008 line documentation. There is no C API for warning control.
15613 35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	1009 \end{cfuncdesc}
35749a557f1e Document Pyerr_Warn(). Guido van Rossum <guido@python.org> parents: 15453 diff changeset	1010
16872 5280e8439d55 Document PyErr_WarnExplicit(). Guido van Rossum <guido@python.org> parents: 16577 diff changeset	1011 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject category, char message,
5280e8439d55 Document PyErr_WarnExplicit(). Guido van Rossum <guido@python.org> parents: 16577 diff changeset	1012 char filename, int lineno, char module, PyObject *registry}
5280e8439d55 Document PyErr_WarnExplicit(). Guido van Rossum <guido@python.org> parents: 16577 diff changeset	1013 Issue a warning message with explicit control over all warning
5280e8439d55 Document PyErr_WarnExplicit(). Guido van Rossum <guido@python.org> parents: 16577 diff changeset	1014 attributes. This is a straightforward wrapper around the Python
5280e8439d55 Document PyErr_WarnExplicit(). Guido van Rossum <guido@python.org> parents: 16577 diff changeset	1015 function \function{warnings.warn_explicit()}, see there for more
5280e8439d55 Document PyErr_WarnExplicit(). Guido van Rossum <guido@python.org> parents: 16577 diff changeset	1016 information. The \var{module} and \var{registry} arguments may be
5280e8439d55 Document PyErr_WarnExplicit(). Guido van Rossum <guido@python.org> parents: 16577 diff changeset	1017 set to \code{NULL} to get the default effect described there.
5280e8439d55 Document PyErr_WarnExplicit(). Guido van Rossum <guido@python.org> parents: 16577 diff changeset	1018 \end{cfuncdesc}
5280e8439d55 Document PyErr_WarnExplicit(). Guido van Rossum <guido@python.org> parents: 16577 diff changeset	1019
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1020 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1021 This function interacts with Python's signal handling. It checks
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1022 whether a signal has been sent to the processes and if so, invokes the
7310 6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	1023 corresponding signal handler. If the
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	1024 \module{signal}\refbimodindex{signal} module is supported, this can
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	1025 invoke a signal handler written in Python. In all cases, the default
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1026 effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1027 \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1028 \exception{KeyboardInterrupt} exception. If an exception is raised the
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1029 error indicator is set and the function returns \code{1}; otherwise
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1030 the function returns \code{0}. The error indicator may or may not be
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1031 cleared if it was previously set.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1032 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1033
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1034 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1035 This function is obsolete. It simulates the effect of a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1036 \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1037 \cfunction{PyErr_CheckSignals()} is called,
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1038 \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1039 \exception{KeyboardInterrupt} will be raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1040 It may be called without holding the interpreter lock.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1041 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1042
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1043 \begin{cfuncdesc}{PyObject}{PyErr_NewException}{char name,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1044 PyObject *base,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1045 PyObject *dict}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1046 This utility function creates and returns a new exception object. The
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1047 \var{name} argument must be the name of the new exception, a C string
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1048 of the form \code{module.class}. The \var{base} and
13150 f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1049 \var{dict} arguments are normally \NULL{}. This creates a
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1050 class object derived from the root for all exceptions, the built-in
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1051 name \exception{Exception} (accessible in C as
13150 f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1052 \cdata{PyExc_Exception}). The \member{__module__} attribute of the
f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1053 new class is set to the first part (up to the last dot) of the
f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1054 \var{name} argument, and the class name is set to the last part (after
f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1055 the last dot). The \var{base} argument can be used to specify an
f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1056 alternate base class. The \var{dict} argument can be used to specify
f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1057 a dictionary of class variables and methods.
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1058 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1059
14330 6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1060 \begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj}
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1061 This utility function prints a warning message to \var{sys.stderr}
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1062 when an exception has been set but it is impossible for the
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1063 interpreter to actually raise the exception. It is used, for example,
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1064 when an exception occurs in an \member{__del__} method.
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1065
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1066 The function is called with a single argument \var{obj} that
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1067 identifies where the context in which the unraisable exception
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1068 occurred. The repr of \var{obj} will be printed in the warning
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1069 message.
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable Jeremy Hylton <jeremy@alum.mit.edu> parents: 14279 diff changeset	1070 \end{cfuncdesc}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1071
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	1072 \section{Standard Exceptions \label{standardExceptions}}
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1073
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1074 All standard Python exceptions are available as global variables whose
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1075 names are \samp{PyExc_} followed by the Python exception name. These
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1076 have the type \ctype{PyObject*}; they are all class objects. For
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1077 completeness, here are all the variables:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1078
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1079 \begin{tableiii}{l\|l\|c}{cdata}{C Name}{Python Name}{Notes}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1080 \lineiii{PyExc_Exception}{\exception{Exception}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1081 \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1082 \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1083 \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1084 \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1085 \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1086 \lineiii{PyExc_EOFError}{\exception{EOFError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1087 \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1088 \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1089 \lineiii{PyExc_IOError}{\exception{IOError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1090 \lineiii{PyExc_ImportError}{\exception{ImportError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1091 \lineiii{PyExc_IndexError}{\exception{IndexError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1092 \lineiii{PyExc_KeyError}{\exception{KeyError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1093 \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1094 \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1095 \lineiii{PyExc_NameError}{\exception{NameError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1096 \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1097 \lineiii{PyExc_OSError}{\exception{OSError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1098 \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1099 \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1100 \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1101 \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1102 \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1103 \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1104 \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
13929 f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	1105 \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(2)}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1106 \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1107 \end{tableiii}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1108
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1109 \noindent
13929 f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	1110 Notes:
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1111 \begin{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1112 \item[(1)]
13150 f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1113 This is a base class for other standard exceptions.
13929 f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	1114
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	1115 \item[(2)]
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	1116 Only defined on Windows; protect code that uses this by testing that
f194d8b24865 PyRun_InteractiveOne(), Fred Drake <fdrake@acm.org> parents: 13920 diff changeset	1117 the preprocessor macro \code{MS_WINDOWS} is defined.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1118 \end{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1119
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1120
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1121 \section{Deprecation of String Exceptions}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1122
13150 f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1123 All exceptions built into Python or provided in the standard library
f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1124 are derived from \exception{Exception}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1125 \withsubitem{(built-in exception)}{\ttindex{Exception}}
13150 f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1126
f1f4d822e761 Update comments relating to the removal of the -X option and of string Fred Drake <fdrake@acm.org> parents: 13053 diff changeset	1127 String exceptions are still supported in the interpreter to allow
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1128 existing code to run unmodified, but this will also change in a future
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1129 release.
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	1130
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1131
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	1132 \chapter{Utilities \label{utilities}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1133
18785 b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1134 The functions in this chapter perform various utility tasks, ranging
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1135 from helping C code be more portable across platforms, using Python
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1136 modules from C, and parsing function arguments and constructing Python
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1137 values from C values.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1138
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1139
18575 670464c94b92 Fix the markup of the caret charater in a couple of places; LaTeX's Fred Drake <fdrake@acm.org> parents: 18481 diff changeset	1140 \section{Operating System Utilities \label{os}}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1141
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1142 \begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE fp, char filename}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1143 Return true (nonzero) if the standard I/O file \var{fp} with name
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1144 \var{filename} is deemed interactive. This is the case for files for
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1145 which \samp{isatty(fileno(\var{fp}))} is true. If the global flag
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	1146 \cdata{Py_InteractiveFlag} is true, this function also returns true if
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	1147 the \var{filename} pointer is \NULL{} or if the name is equal to one of
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	1148 the strings \code{'<stdin>'} or \code{'???'}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1149 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1150
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1151 \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1152 Return the time of last modification of the file \var{filename}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1153 The result is encoded in the same way as the timestamp returned by
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1154 the standard C library function \cfunction{time()}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1155 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1156
13053 b00744237877 Added documentation for PyOS_AfterFork(). Fred Drake <fdrake@acm.org> parents: 12947 diff changeset	1157 \begin{cfuncdesc}{void}{PyOS_AfterFork}{}
b00744237877 Added documentation for PyOS_AfterFork(). Fred Drake <fdrake@acm.org> parents: 12947 diff changeset	1158 Function to update some internal state after a process fork; this
b00744237877 Added documentation for PyOS_AfterFork(). Fred Drake <fdrake@acm.org> parents: 12947 diff changeset	1159 should be called in the new process if the Python interpreter will
b00744237877 Added documentation for PyOS_AfterFork(). Fred Drake <fdrake@acm.org> parents: 12947 diff changeset	1160 continue to be used. If a new executable is loaded into the new
b00744237877 Added documentation for PyOS_AfterFork(). Fred Drake <fdrake@acm.org> parents: 12947 diff changeset	1161 process, this function does not need to be called.
b00744237877 Added documentation for PyOS_AfterFork(). Fred Drake <fdrake@acm.org> parents: 12947 diff changeset	1162 \end{cfuncdesc}
b00744237877 Added documentation for PyOS_AfterFork(). Fred Drake <fdrake@acm.org> parents: 12947 diff changeset	1163
14279 b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	1164 \begin{cfuncdesc}{int}{PyOS_CheckStack}{}
b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	1165 Return true when the interpreter runs out of stack space. This is a
b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	1166 reliable check, but is only available when \code{USE_STACKCHECK} is
b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	1167 defined (currently on Windows using the Microsoft Visual C++ compiler
b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	1168 and on the Macintosh). \code{USE_CHECKSTACK} will be defined
b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	1169 automatically; you should never change the definition in your own
b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	1170 code.
b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	1171 \end{cfuncdesc}
b1a0fd3df1fc Document PyOS_CheckStack(). Fred Drake <fdrake@acm.org> parents: 13959 diff changeset	1172
14635 db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1173 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1174 Return the current signal handler for signal \var{i}.
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1175 This is a thin wrapper around either \cfunction{sigaction} or
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1176 \cfunction{signal}. Do not call those functions directly!
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1177 \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}.
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1178 \end{cfuncdesc}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1179
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1180 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1181 Set the signal handler for signal \var{i} to be \var{h};
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1182 return the old signal handler.
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1183 This is a thin wrapper around either \cfunction{sigaction} or
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1184 \cfunction{signal}. Do not call those functions directly!
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1185 \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}.
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1186 \end{cfuncdesc}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig(). Guido van Rossum <guido@python.org> parents: 14557 diff changeset	1187
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1188
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	1189 \section{Process Control \label{processControl}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1190
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1191 \begin{cfuncdesc}{void}{Py_FatalError}{char *message}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1192 Print a fatal error message and kill the process. No cleanup is
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1193 performed. This function should only be invoked when a condition is
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1194 detected that would make it dangerous to continue using the Python
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1195 interpreter; e.g., when the object administration appears to be
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1196 corrupted. On \UNIX{}, the standard C library function
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1197 \cfunction{abort()}\ttindex{abort()} is called which will attempt to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1198 produce a \file{core} file.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1199 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1200
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1201 \begin{cfuncdesc}{void}{Py_Exit}{int status}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1202 Exit the current process. This calls
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1203 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1204 then calls the standard C library function
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1205 \code{exit(\var{status})}\ttindex{exit()}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1206 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1207
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1208 \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1209 Register a cleanup function to be called by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1210 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1211 The cleanup function will be called with no arguments and should
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1212 return no value. At most 32 \index{cleanup functions}cleanup
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1213 functions can be registered.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1214 When the registration is successful, \cfunction{Py_AtExit()} returns
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1215 \code{0}; on failure, it returns \code{-1}. The cleanup function
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1216 registered last is called first. Each cleanup function will be called
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1217 at most once. Since Python's internal finallization will have
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1218 completed before the cleanup function, no Python APIs should be called
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1219 by \var{func}.
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1220 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1221
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	1222
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	1223 \section{Importing Modules \label{importing}}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1224
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1225 \begin{cfuncdesc}{PyObject}{PyImport_ImportModule}{char name}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1226 This is a simplified interface to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1227 \cfunction{PyImport_ImportModuleEx()} below, leaving the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1228 \var{globals} and \var{locals} arguments set to \NULL{}. When the
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	1229 \var{name} argument contains a dot (when it specifies a
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1230 submodule of a package), the \var{fromlist} argument is set to the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1231 list \code{['*']} so that the return value is the named module rather
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1232 than the top-level package containing it as would otherwise be the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1233 case. (Unfortunately, this has an additional side effect when
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1234 \var{name} in fact specifies a subpackage instead of a submodule: the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1235 submodules specified in the package's \code{__all__} variable are
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1236 \index{package variable!\code{__all__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1237 \withsubitem{(package variable)}{\ttindex{__all__}}loaded.) Return a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1238 new reference to the imported module, or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1239 \NULL{} with an exception set on failure (the module may still be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1240 created in this case --- examine \code{sys.modules} to find out).
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1241 \withsubitem{(in module sys)}{\ttindex{modules}}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1242 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1243
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1244 \begin{cfuncdesc}{PyObject}{PyImport_ImportModuleEx}{char name,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1245 PyObject globals, PyObject locals, PyObject *fromlist}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1246 Import a module. This is best described by referring to the built-in
7309 d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1247 Python function \function{__import__()}\bifuncindex{__import__}, as
d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1248 the standard \function{__import__()} function calls this function
d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1249 directly.
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1250
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1251 The return value is a new reference to the imported module or
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	1252 top-level package, or \NULL{} with an exception set on failure
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	1253 (the module may still be created in this case). Like for
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1254 \function{__import__()}, the return value when a submodule of a
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1255 package was requested is normally the top-level package, unless a
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1256 non-empty \var{fromlist} was given.
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1257 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1258
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1259 \begin{cfuncdesc}{PyObject}{PyImport_Import}{PyObject name}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1260 This is a higher-level interface that calls the current ``import hook
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1261 function''. It invokes the \function{__import__()} function from the
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1262 \code{__builtins__} of the current globals. This means that the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1263 import is done using whatever import hooks are installed in the
7310 6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	1264 current environment, e.g. by \module{rexec}\refstmodindex{rexec} or
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	1265 \module{ihooks}\refstmodindex{ihooks}.
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1266 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1267
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1268 \begin{cfuncdesc}{PyObject}{PyImport_ReloadModule}{PyObject m}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1269 Reload a module. This is best described by referring to the built-in
7309 d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1270 Python function \function{reload()}\bifuncindex{reload}, as the standard
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1271 \function{reload()} function calls this function directly. Return a
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1272 new reference to the reloaded module, or \NULL{} with an exception set
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1273 on failure (the module still exists in this case).
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1274 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1275
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1276 \begin{cfuncdesc}{PyObject}{PyImport_AddModule}{char name}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1277 Return the module object corresponding to a module name. The
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1278 \var{name} argument may be of the form \code{package.module}). First
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1279 check the modules dictionary if there's one there, and if not, create
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1280 a new one and insert in in the modules dictionary.
9476 1ea6d2356e52 Warn that AddModule doesn't import the module. Guido van Rossum <guido@python.org> parents: 9383 diff changeset	1281 Warning: this function does not load or import the module; if the
1ea6d2356e52 Warn that AddModule doesn't import the module. Guido van Rossum <guido@python.org> parents: 9383 diff changeset	1282 module wasn't already loaded, you will get an empty module object.
1ea6d2356e52 Warn that AddModule doesn't import the module. Guido van Rossum <guido@python.org> parents: 9383 diff changeset	1283 Use \cfunction{PyImport_ImportModule()} or one of its variants to
1ea6d2356e52 Warn that AddModule doesn't import the module. Guido van Rossum <guido@python.org> parents: 9383 diff changeset	1284 import a module.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1285 Return \NULL{} with an exception set on failure.
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1286 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1287
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1288 \begin{cfuncdesc}{PyObject}{PyImport_ExecCodeModule}{char name, PyObject *co}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1289 Given a module name (possibly of the form \code{package.module}) and a
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1290 code object read from a Python bytecode file or obtained from the
7309 d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1291 built-in function \function{compile()}\bifuncindex{compile}, load the
d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1292 module. Return a new reference to the module object, or \NULL{} with
d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1293 an exception set if an error occurred (the module may still be created
d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1294 in this case). (This function would reload the module if it was
d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1295 already imported.)
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1296 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1297
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1298 \begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1299 Return the magic number for Python bytecode files (a.k.a.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1300 \file{.pyc} and \file{.pyo} files). The magic number should be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1301 present in the first four bytes of the bytecode file, in little-endian
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1302 byte order.
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1303 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1304
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1305 \begin{cfuncdesc}{PyObject*}{PyImport_GetModuleDict}{}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1306 Return the dictionary used for the module administration
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1307 (a.k.a. \code{sys.modules}). Note that this is a per-interpreter
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1308 variable.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1309 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1310
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1311 \begin{cfuncdesc}{void}{_PyImport_Init}{}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1312 Initialize the import mechanism. For internal use only.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1313 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1314
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1315 \begin{cfuncdesc}{void}{PyImport_Cleanup}{}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1316 Empty the module table. For internal use only.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1317 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1318
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1319 \begin{cfuncdesc}{void}{_PyImport_Fini}{}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1320 Finalize the import mechanism. For internal use only.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1321 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1322
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1323 \begin{cfuncdesc}{PyObject}{_PyImport_FindExtension}{char , char *}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1324 For internal use only.
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	1325 \end{cfuncdesc}
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	1326
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1327 \begin{cfuncdesc}{PyObject}{_PyImport_FixupExtension}{char , char *}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1328 For internal use only.
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	1329 \end{cfuncdesc}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1330
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	1331 \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	1332 Load a frozen module named \var{name}. Return \code{1} for success,
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	1333 \code{0} if the module is not found, and \code{-1} with an exception
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	1334 set if the initialization failed. To access the imported module on a
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	1335 successful load, use \cfunction{PyImport_ImportModule()}.
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1336 (Note the misnomer --- this function would reload the module if it was
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1337 already imported.)
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1338 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1339
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1340 \begin{ctypedesc}[_frozen]{struct _frozen}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1341 This is the structure type definition for frozen module descriptors,
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1342 as generated by the \program{freeze}\index{freeze utility} utility
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1343 (see \file{Tools/freeze/} in the Python source distribution). Its
14337 3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1344 definition, found in \file{Include/import.h}, is:
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1345
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	1346 \begin{verbatim}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1347 struct _frozen {
6480 727b52031212 struct _frozen: Fred Drake <fdrake@acm.org> parents: 6417 diff changeset	1348 char *name;
727b52031212 struct _frozen: Fred Drake <fdrake@acm.org> parents: 6417 diff changeset	1349 unsigned char *code;
727b52031212 struct _frozen: Fred Drake <fdrake@acm.org> parents: 6417 diff changeset	1350 int size;
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1351 };
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	1352 \end{verbatim}
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1353 \end{ctypedesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1354
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	1355 \begin{cvardesc}{struct _frozen*}{PyImport_FrozenModules}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	1356 This pointer is initialized to point to an array of \ctype{struct
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1357 _frozen} records, terminated by one whose members are all
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1358 \NULL{} or zero. When a frozen module is imported, it is searched in
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1359 this table. Third-party code could play tricks with this to provide a
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1360 dynamically created collection of frozen modules.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1361 \end{cvardesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1362
14337 3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1363 \begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1364 void (*initfunc)(void)}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1365 Add a single module to the existing table of built-in modules. This
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1366 is a convenience wrapper around \cfunction{PyImport_ExtendInittab()},
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1367 returning \code{-1} if the table could not be extended. The new
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1368 module can be imported by the name \var{name}, and uses the function
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1369 \var{initfunc} as the initialization function called on the first
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1370 attempted import. This should be called before
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1371 \cfunction{Py_Initialize()}.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1372 \end{cfuncdesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1373
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1374 \begin{ctypedesc}[_inittab]{struct _inittab}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1375 Structure describing a single entry in the list of built-in modules.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1376 Each of these structures gives the name and initialization function
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1377 for a module built into the interpreter. Programs which embed Python
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1378 may use an array of these structures in conjunction with
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1379 \cfunction{PyImport_ExtendInittab()} to provide additional built-in
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1380 modules. The structure is defined in \file{Include/import.h} as:
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1381
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1382 \begin{verbatim}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1383 struct _inittab {
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1384 char *name;
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1385 void (*initfunc)(void);
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1386 };
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1387 \end{verbatim}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1388 \end{ctypedesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1389
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1390 \begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1391 Add a collection of modules to the table of built-in modules. The
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1392 \var{newtab} array must end with a sentinel entry which contains
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1393 \NULL{} for the \member{name} field; failure to provide the sentinel
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1394 value can result in a memory fault. Returns \code{0} on success or
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1395 \code{-1} if insufficient memory could be allocated to extend the
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1396 internal table. In the event of failure, no modules are added to the
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1397 internal table. This should be called before
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1398 \cfunction{Py_Initialize()}.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1399 \end{cfuncdesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and Fred Drake <fdrake@acm.org> parents: 14330 diff changeset	1400
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	1401
18785 b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1402 \section{Parsing arguements and building values
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1403 \label{arg-parsing}}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1404
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1405 These functions are useful when creating your own extensions functions
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1406 and methods. Additional information and examples are available in
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1407 \citetitle[../ext/ext.html]{Extending and Embedding the Python
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1408 Interpreter}.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1409
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1410 \begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject args, char format,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1411 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1412 Parse the parameters of a function that takes only positional
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1413 parameters into local variables. Returns true on success; on
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1414 failure, it returns false and raises the appropriate exception. See
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1415 \citetitle[../ext/parseTuple.html]{Extending and Embedding the
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1416 Python Interpreter} for more information.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1417 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1418
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1419 \begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1420 PyObject kw, char format, char *keywords[],
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1421 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1422 Parse the parameters of a function that takes both positional and
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1423 keyword parameters into local variables. Returns true on success;
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1424 on failure, it returns false and raises the appropriate exception.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1425 See \citetitle[../ext/parseTupleAndKeywords.html]{Extending and
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1426 Embedding the Python Interpreter} for more information.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1427 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1428
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1429 \begin{cfuncdesc}{int}{PyArg_Parse}{PyObject args, char format,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1430 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1431 Function used to deconstruct the argument lists of ``old-style''
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1432 functions --- these are functions which use the
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1433 \constant{METH_OLDARGS} parameter parsing method. This is not
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1434 recommended for use in parameter parsing in new code, and most code
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1435 in the standard interpreter has been modified to no longer use this
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1436 for that purpose. It does remain a convenient way to decompose
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1437 other tuples, however, and may continue to be used for that
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1438 purpose.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1439 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1440
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1441 \begin{cfuncdesc}{PyObject}{Py_BuildValue}{char format,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1442 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1443 Create a new value based on a format string similar to those
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1444 accepted by the \cfunction{PyArg_Parse*()} family of functions and a
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1445 sequence of values. Returns the value or \NULL{} in the case of an
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1446 error; an exception will be raised if \NULL{} is returned. For more
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1447 information on the format string and additional parameters, see
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1448 \citetitle[../ext/buildValue.html]{Extending and Embedding the
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1449 Python Interpreter}.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1450 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1451
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1452
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	1453
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	1454 \chapter{Abstract Objects Layer \label{abstract}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1455
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1456 The functions in this chapter interact with Python objects regardless
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1457 of their type, or with wide classes of object types (e.g. all
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1458 numerical types, or all sequence types). When used on object types
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1459 for which they do not apply, they will raise a Python exception.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1460
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	1461 \section{Object Protocol \label{object}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1462
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1463 \begin{cfuncdesc}{int}{PyObject_Print}{PyObject o, FILE fp, int flags}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1464 Print an object \var{o}, on file \var{fp}. Returns \code{-1} on error.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1465 The flags argument is used to enable certain printing options. The
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1466 only option currently supported is \constant{Py_PRINT_RAW}; if given,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1467 the \function{str()} of the object is written instead of the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1468 \function{repr()}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1469 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1470
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1471 \begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject o, char attr_name}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1472 Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1473 \code{0} otherwise. This is equivalent to the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1474 \samp{hasattr(\var{o}, \var{attr_name})}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1475 This function always succeeds.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1476 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1477
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1478 \begin{cfuncdesc}{PyObject}{PyObject_GetAttrString}{PyObject o,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1479 char *attr_name}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1480 Retrieve an attribute named \var{attr_name} from object \var{o}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1481 Returns the attribute value on success, or \NULL{} on failure.
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1482 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1483 \samp{\var{o}.\var{attr_name}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1484 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1485
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1486
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1487 \begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject o, PyObject attr_name}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1488 Returns \code{1} if \var{o} has the attribute \var{attr_name}, and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1489 \code{0} otherwise. This is equivalent to the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1490 \samp{hasattr(\var{o}, \var{attr_name})}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1491 This function always succeeds.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1492 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1493
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1494
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1495 \begin{cfuncdesc}{PyObject}{PyObject_GetAttr}{PyObject o,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1496 PyObject *attr_name}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1497 Retrieve an attribute named \var{attr_name} from object \var{o}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1498 Returns the attribute value on success, or \NULL{} on failure.
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1499 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1500 \samp{\var{o}.\var{attr_name}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1501 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1502
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1503
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1504 \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1505 char attr_name, PyObject v}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1506 Set the value of the attribute named \var{attr_name}, for object
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1507 \var{o}, to the value \var{v}. Returns \code{-1} on failure. This is
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1508 the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1509 \var{v}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1510 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1511
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1512
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1513 \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1514 PyObject attr_name, PyObject v}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1515 Set the value of the attribute named \var{attr_name}, for
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1516 object \var{o},
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1517 to the value \var{v}. Returns \code{-1} on failure. This is
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1518 the equivalent of the Python statement \samp{\var{o}.\var{attr_name} =
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1519 \var{v}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1520 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1521
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1522
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1523 \begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject o, char attr_name}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1524 Delete attribute named \var{attr_name}, for object \var{o}. Returns
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1525 \code{-1} on failure. This is the equivalent of the Python
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1526 statement: \samp{del \var{o}.\var{attr_name}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1527 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1528
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1529
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1530 \begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject o, PyObject attr_name}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1531 Delete attribute named \var{attr_name}, for object \var{o}. Returns
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1532 \code{-1} on failure. This is the equivalent of the Python
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1533 statement \samp{del \var{o}.\var{attr_name}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1534 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1535
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1537 \begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject o1, PyObject o2, int *result}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1538 Compare the values of \var{o1} and \var{o2} using a routine provided
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1539 by \var{o1}, if one exists, otherwise with a routine provided by
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1540 \var{o2}. The result of the comparison is returned in \var{result}.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1541 Returns \code{-1} on failure. This is the equivalent of the Python
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1542 statement\bifuncindex{cmp} \samp{\var{result} = cmp(\var{o1}, \var{o2})}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1543 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1544
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1545
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1546 \begin{cfuncdesc}{int}{PyObject_Compare}{PyObject o1, PyObject o2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1547 Compare the values of \var{o1} and \var{o2} using a routine provided
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1548 by \var{o1}, if one exists, otherwise with a routine provided by
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1549 \var{o2}. Returns the result of the comparison on success. On error,
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1550 the value returned is undefined; use \cfunction{PyErr_Occurred()} to
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1551 detect an error. This is equivalent to the Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1552 expression\bifuncindex{cmp} \samp{cmp(\var{o1}, \var{o2})}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1553 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1554
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1555
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1556 \begin{cfuncdesc}{PyObject}{PyObject_Repr}{PyObject o}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1557 Compute a string representation of object \var{o}. Returns the
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1558 string representation on success, \NULL{} on failure. This is
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1559 the equivalent of the Python expression \samp{repr(\var{o})}.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1560 Called by the \function{repr()}\bifuncindex{repr} built-in function
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1561 and by reverse quotes.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1562 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1563
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1564
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1565 \begin{cfuncdesc}{PyObject}{PyObject_Str}{PyObject o}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1566 Compute a string representation of object \var{o}. Returns the
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1567 string representation on success, \NULL{} on failure. This is
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1568 the equivalent of the Python expression \samp{str(\var{o})}.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1569 Called by the \function{str()}\bifuncindex{str} built-in function and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1570 by the \keyword{print} statement.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1571 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1572
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1573
15952 1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str() Marc-André Lemburg <mal@egenix.com> parents: 15733 diff changeset	1574 \begin{cfuncdesc}{PyObject}{PyObject_Unicode}{PyObject o}
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str() Marc-André Lemburg <mal@egenix.com> parents: 15733 diff changeset	1575 Compute a Unicode string representation of object \var{o}. Returns the
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str() Marc-André Lemburg <mal@egenix.com> parents: 15733 diff changeset	1576 Unicode string representation on success, \NULL{} on failure. This is
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str() Marc-André Lemburg <mal@egenix.com> parents: 15733 diff changeset	1577 the equivalent of the Python expression \samp{unistr(\var{o})}.
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str() Marc-André Lemburg <mal@egenix.com> parents: 15733 diff changeset	1578 Called by the \function{unistr()}\bifuncindex{unistr} built-in function.
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str() Marc-André Lemburg <mal@egenix.com> parents: 15733 diff changeset	1579 \end{cfuncdesc}
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str() Marc-André Lemburg <mal@egenix.com> parents: 15733 diff changeset	1580
17242 1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1581 \begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject inst, PyObject cls}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1582 Return \code{1} if \var{inst} is an instance of the class \var{cls} or
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1583 a subclass of \var{cls}. If \var{cls} is a type object rather than a
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1584 class object, \cfunction{PyObject_IsInstance()} returns \code{1} if
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1585 \var{inst} is of type \var{cls}. If \var{inst} is not a class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1586 instance and \var{cls} is neither a type object or class object,
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1587 \var{inst} must have a \member{__class__} attribute --- the class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1588 relationship of the value of that attribute with \var{cls} will be
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1589 used to determine the result of this function.
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1590 \versionadded{2.1}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1591 \end{cfuncdesc}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1592
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1593 Subclass determination is done in a fairly straightforward way, but
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1594 includes a wrinkle that implementors of extensions to the class system
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1595 may want to be aware of. If \class{A} and \class{B} are class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1596 objects, \class{B} is a subclass of \class{A} if it inherits from
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1597 \class{A} either directly or indirectly. If either is not a class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1598 object, a more general mechanism is used to determine the class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1599 relationship of the two objects. When testing if \var{B} is a
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1600 subclass of \var{A}, if \var{A} is \var{B},
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1601 \cfunction{PyObject_IsSubclass()} returns true. If \var{A} and
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1602 \var{B} are different objects, \var{B}'s \member{__bases__} attribute
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1603 is searched in a depth-first fashion for \var{A} --- the presence of
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1604 the \member{__bases__} attribute is considered sufficient for this
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1605 determination.
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1606
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1607 \begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived,
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1608 PyObject *cls}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1609 Returns \code{1} if the class \var{derived} is identical to or derived
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1610 from the class \var{cls}, otherwise returns \code{0}. In case of an
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1611 error, returns \code{-1}. If either \var{derived} or \var{cls} is not
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1612 an actual class object, this function uses the generic algorithm
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1613 described above.
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1614 \versionadded{2.1}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1615 \end{cfuncdesc}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass(). Fred Drake <fdrake@acm.org> parents: 17209 diff changeset	1616
15952 1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str() Marc-André Lemburg <mal@egenix.com> parents: 15733 diff changeset	1617
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1618 \begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1619 Determine if the object \var{o} is callable. Return \code{1} if the
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1620 object is callable and \code{0} otherwise.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1621 This function always succeeds.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1622 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1623
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1624
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1625 \begin{cfuncdesc}{PyObject}{PyObject_CallObject}{PyObject callable_object,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1626 PyObject *args}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1627 Call a callable Python object \var{callable_object}, with
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1628 arguments given by the tuple \var{args}. If no arguments are
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1629 needed, then \var{args} may be \NULL{}. Returns the result of the
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1630 call on success, or \NULL{} on failure. This is the equivalent
18944 a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	1631 of the Python expression \samp{apply(\var{callable_object},
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	1632 \var{args})} or \samp{\var{callable_object}(*\var{args})}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1633 \bifuncindex{apply}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1634 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1635
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	1636 \begin{cfuncdesc}{PyObject}{PyObject_CallFunction}{PyObject callable_object,
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	1637 char *format, ...}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1638 Call a callable Python object \var{callable_object}, with a
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1639 variable number of C arguments. The C arguments are described
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1640 using a \cfunction{Py_BuildValue()} style format string. The format may
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1641 be \NULL{}, indicating that no arguments are provided. Returns the
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1642 result of the call on success, or \NULL{} on failure. This is
18944 a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	1643 the equivalent of the Python expression
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	1644 \samp{apply(\var{callable_object}\var{args})} or
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	1645 \samp{\var{callable_object}(*\var{args})}.
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	1646 \bifuncindex{apply}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1647 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1648
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1649
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	1650 \begin{cfuncdesc}{PyObject}{PyObject_CallMethod}{PyObject o,
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	1651 char method, char format, ...}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1652 Call the method named \var{m} of object \var{o} with a variable number
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1653 of C arguments. The C arguments are described by a
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1654 \cfunction{Py_BuildValue()} format string. The format may be \NULL{},
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1655 indicating that no arguments are provided. Returns the result of the
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1656 call on success, or \NULL{} on failure. This is the equivalent of the
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1657 Python expression \samp{\var{o}.\var{method}(\var{args})}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1658 Note that special method names, such as \method{__add__()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1659 \method{__getitem__()}, and so on are not supported. The specific
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1660 abstract-object routines for these must be used.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1661 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1662
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1663
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1664 \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1665 Compute and return the hash value of an object \var{o}. On
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1666 failure, return \code{-1}. This is the equivalent of the Python
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1667 expression \samp{hash(\var{o})}.\bifuncindex{hash}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1668 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1669
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1670
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1671 \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1672 Returns \code{1} if the object \var{o} is considered to be true, and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1673 \code{0} otherwise. This is equivalent to the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1674 \samp{not not \var{o}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1675 This function always succeeds.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1676 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1677
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1678
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1679 \begin{cfuncdesc}{PyObject}{PyObject_Type}{PyObject o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1680 On success, returns a type object corresponding to the object
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1681 type of object \var{o}. On failure, returns \NULL{}. This is
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1682 equivalent to the Python expression \samp{type(\var{o})}.
7309 d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1683 \bifuncindex{type}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1684 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1685
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1686 \begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1687 Return the length of object \var{o}. If the object \var{o} provides
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1688 both sequence and mapping protocols, the sequence length is
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1689 returned. On error, \code{-1} is returned. This is the equivalent
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1690 to the Python expression \samp{len(\var{o})}.\bifuncindex{len}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1691 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1692
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1693
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1694 \begin{cfuncdesc}{PyObject}{PyObject_GetItem}{PyObject o, PyObject *key}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1695 Return element of \var{o} corresponding to the object \var{key} or
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1696 \NULL{} on failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1697 \samp{\var{o}[\var{key}]}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1698 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1699
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1700
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1701 \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1702 PyObject key, PyObject v}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1703 Map the object \var{key} to the value \var{v}.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1704 Returns \code{-1} on failure. This is the equivalent
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1705 of the Python statement \samp{\var{o}[\var{key}] = \var{v}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1706 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1707
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1708
9931 00fc18ac6aeb Header for PyObject_DelItem() mentioned non-existing 3rd argument. Guido van Rossum <guido@python.org> parents: 9476 diff changeset	1709 \begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject o, PyObject key}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1710 Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1711 failure. This is the equivalent of the Python statement \samp{del
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1712 \var{o}[\var{key}]}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1713 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1714
13592 9ca50e2433eb Document PyObject_AsFileDescriptor Andrew M. Kuchling <amk@amk.ca> parents: 13404 diff changeset	1715 \begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o}
9ca50e2433eb Document PyObject_AsFileDescriptor Andrew M. Kuchling <amk@amk.ca> parents: 13404 diff changeset	1716 Derives a file-descriptor from a Python object. If the object
9ca50e2433eb Document PyObject_AsFileDescriptor Andrew M. Kuchling <amk@amk.ca> parents: 13404 diff changeset	1717 is an integer or long integer, its value is returned. If not, the
9ca50e2433eb Document PyObject_AsFileDescriptor Andrew M. Kuchling <amk@amk.ca> parents: 13404 diff changeset	1718 object's \method{fileno()} method is called if it exists; the method
9ca50e2433eb Document PyObject_AsFileDescriptor Andrew M. Kuchling <amk@amk.ca> parents: 13404 diff changeset	1719 must return an integer or long integer, which is returned as the file
9ca50e2433eb Document PyObject_AsFileDescriptor Andrew M. Kuchling <amk@amk.ca> parents: 13404 diff changeset	1720 descriptor value. Returns \code{-1} on failure.
9ca50e2433eb Document PyObject_AsFileDescriptor Andrew M. Kuchling <amk@amk.ca> parents: 13404 diff changeset	1721 \end{cfuncdesc}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1722
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1723
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	1724 \section{Number Protocol \label{number}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1725
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1726 \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1727 Returns \code{1} if the object \var{o} provides numeric protocols, and
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1728 false otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1729 This function always succeeds.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1730 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1731
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1732
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1733 \begin{cfuncdesc}{PyObject}{PyNumber_Add}{PyObject o1, PyObject *o2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1734 Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1735 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1736 \samp{\var{o1} + \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1737 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1738
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1739
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1740 \begin{cfuncdesc}{PyObject}{PyNumber_Subtract}{PyObject o1, PyObject *o2}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1741 Returns the result of subtracting \var{o2} from \var{o1}, or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1742 \NULL{} on failure. This is the equivalent of the Python expression
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1743 \samp{\var{o1} - \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1744 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1745
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1746
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1747 \begin{cfuncdesc}{PyObject}{PyNumber_Multiply}{PyObject o1, PyObject *o2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1748 Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1749 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1750 \samp{\var{o1} * \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1751 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1752
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1753
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1754 \begin{cfuncdesc}{PyObject}{PyNumber_Divide}{PyObject o1, PyObject *o2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1755 Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1756 failure.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1757 This is the equivalent of the Python expression \samp{\var{o1} /
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1758 \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1759 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1760
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1761
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1762 \begin{cfuncdesc}{PyObject}{PyNumber_FloorDivide}{PyObject o1, PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1763 Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1764 failure. This is equivalent to the ``classic'' division of integers.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1765 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1766 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1767
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1768
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1769 \begin{cfuncdesc}{PyObject}{PyNumber_TrueDivide}{PyObject o1, PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1770 Return a reasonable approximation for the mathematical value of
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1771 \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1772 is ``approximate'' because binary floating point numbers are
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1773 approximate; it is not possible to represent all real numbers in base
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1774 two. This function can return a floating point value when passed two
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1775 integers.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1776 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1777 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1778
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1779
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1780 \begin{cfuncdesc}{PyObject}{PyNumber_Remainder}{PyObject o1, PyObject *o2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1781 Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1782 failure. This is the equivalent of the Python expression
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1783 \samp{\var{o1} \%\ \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1784 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1785
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1786
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1787 \begin{cfuncdesc}{PyObject}{PyNumber_Divmod}{PyObject o1, PyObject *o2}
7309 d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1788 See the built-in function \function{divmod()}\bifuncindex{divmod}.
d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1789 Returns \NULL{} on failure. This is the equivalent of the Python
d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1790 expression \samp{divmod(\var{o1}, \var{o2})}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1791 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1792
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1793
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1794 \begin{cfuncdesc}{PyObject}{PyNumber_Power}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1795 PyObject o2, PyObject o3}
7309 d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1796 See the built-in function \function{pow()}\bifuncindex{pow}. Returns
d7266372dd37 Added index enties for the Python built-in functions, where appropriate. Fred Drake <fdrake@acm.org> parents: 7308 diff changeset	1797 \NULL{} on failure. This is the equivalent of the Python expression
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1798 \samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3} is optional.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1799 If \var{o3} is to be ignored, pass \cdata{Py_None} in its place
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1800 (passing \NULL{} for \var{o3} would cause an illegal memory access).
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1801 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1802
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1803
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1804 \begin{cfuncdesc}{PyObject}{PyNumber_Negative}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1805 Returns the negation of \var{o} on success, or \NULL{} on failure.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1806 This is the equivalent of the Python expression \samp{-\var{o}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1807 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1808
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1809
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1810 \begin{cfuncdesc}{PyObject}{PyNumber_Positive}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1811 Returns \var{o} on success, or \NULL{} on failure.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1812 This is the equivalent of the Python expression \samp{+\var{o}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1813 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1814
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1815
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1816 \begin{cfuncdesc}{PyObject}{PyNumber_Absolute}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1817 Returns the absolute value of \var{o}, or \NULL{} on failure. This is
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1818 the equivalent of the Python expression \samp{abs(\var{o})}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1819 \bifuncindex{abs}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1820 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1821
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1822
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1823 \begin{cfuncdesc}{PyObject}{PyNumber_Invert}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1824 Returns the bitwise negation of \var{o} on success, or \NULL{} on
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1825 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1826 \samp{\~\var{o}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1827 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1828
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1829
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1830 \begin{cfuncdesc}{PyObject}{PyNumber_Lshift}{PyObject o1, PyObject *o2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1831 Returns the result of left shifting \var{o1} by \var{o2} on success,
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1832 or \NULL{} on failure. This is the equivalent of the Python
17480 04daee3ab627 Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping. Fred Drake <fdrake@acm.org> parents: 17336 diff changeset	1833 expression \samp{\var{o1} <\code{<} \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1834 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1835
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1836
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1837 \begin{cfuncdesc}{PyObject}{PyNumber_Rshift}{PyObject o1, PyObject *o2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1838 Returns the result of right shifting \var{o1} by \var{o2} on success,
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1839 or \NULL{} on failure. This is the equivalent of the Python
17480 04daee3ab627 Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping. Fred Drake <fdrake@acm.org> parents: 17336 diff changeset	1840 expression \samp{\var{o1} >\code{>} \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1841 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1842
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1843
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1844 \begin{cfuncdesc}{PyObject}{PyNumber_And}{PyObject o1, PyObject *o2}
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1845 Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1846 \NULL{} on failure. This is the equivalent of the Python expression
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	1847 \samp{\var{o1} \&\ \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1848 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1849
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1850
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1851 \begin{cfuncdesc}{PyObject}{PyNumber_Xor}{PyObject o1, PyObject *o2}
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1852 Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on success,
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1853 or \NULL{} on failure. This is the equivalent of the Python
18576 7d77614fd0b7 Oops, one more caret. Fred Drake <fdrake@acm.org> parents: 18575 diff changeset	1854 expression \samp{\var{o1} \textasciicircum{} \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1855 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1856
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1857 \begin{cfuncdesc}{PyObject}{PyNumber_Or}{PyObject o1, PyObject *o2}
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1858 Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1859 \NULL{} on failure. This is the equivalent of the Python expression
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1860 \samp{\var{o1} \| \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1861 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1862
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1863
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1864 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceAdd}{PyObject o1, PyObject *o2}
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1865 Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1866 failure. The operation is done \emph{in-place} when \var{o1} supports
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1867 it. This is the equivalent of the Python statement \samp{\var{o1} +=
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1868 \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1869 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1870
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1871
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1872 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceSubtract}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1873 PyObject *o2}
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1874 Returns the result of subtracting \var{o2} from \var{o1}, or
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1875 \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1876 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1877 \samp{\var{o1} -= \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1878 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1879
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1880
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1881 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceMultiply}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1882 PyObject *o2}
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1883 Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1884 failure. The operation is done \emph{in-place} when \var{o1} supports it.
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1885 This is the equivalent of the Python statement \samp{\var{o1} *= \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1886 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1887
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1888
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1889 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceDivide}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1890 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1891 Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1892 failure. The operation is done \emph{in-place} when \var{o1} supports
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1893 it. This is the equivalent of the Python statement \samp{\var{o1} /=
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1894 \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1895 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1896
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1897
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1898 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceFloorDivide}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1899 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1900 Returns the mathematical of dividing \var{o1} by \var{o2}, or \NULL{}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1901 on failure. The operation is done \emph{in-place} when \var{o1}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1902 supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1903 \samp{\var{o1} //= \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1904 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1905 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1906
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1907
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1908 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceTrueDivide}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1909 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1910 Return a reasonable approximation for the mathematical value of
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1911 \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1912 is ``approximate'' because binary floating point numbers are
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1913 approximate; it is not possible to represent all real numbers in base
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1914 two. This function can return a floating point value when passed two
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1915 integers. The operation is done \emph{in-place} when \var{o1}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1916 supports it.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1917 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1918 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1919
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1920
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1921 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceRemainder}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1922 PyObject *o2}
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1923 Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1924 failure. The operation is done \emph{in-place} when \var{o1} supports it.
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1925 This is the equivalent of the Python statement \samp{\var{o1} \%= \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1926 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1927
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1928
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1929 \begin{cfuncdesc}{PyObject}{PyNumber_InPlacePower}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1930 PyObject o2, PyObject o3}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1931 See the built-in function \function{pow()}.\bifuncindex{pow} Returns
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1932 \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1933 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1934 \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None}, or an
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1935 in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1936 otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1937 place (passing \NULL{} for \var{o3} would cause an illegal memory
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1938 access).
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1939 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1940
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1941 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceLshift}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1942 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1943 Returns the result of left shifting \var{o1} by \var{o2} on success,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1944 or \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1945 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1946 \samp{\var{o1} <\code{<=} \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1947 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1948
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1949
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1950 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceRshift}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1951 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1952 Returns the result of right shifting \var{o1} by \var{o2} on success,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1953 or \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1954 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1955 \samp{\var{o1} >\code{>=} \var{o2}}.
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1956 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1957
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1958
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1959 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceAnd}{PyObject o1, PyObject *o2}
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	1960 Returns the ``bitwise and'' of \var{o1} and \var{o2} on success
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	1961 and \NULL{} on failure. The operation is done \emph{in-place} when
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1962 \var{o1} supports it. This is the equivalent of the Python statement
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	1963 \samp{\var{o1} \&= \var{o2}}.
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1964 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1965
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1966
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1967 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceXor}{PyObject o1, PyObject *o2}
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1968 Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1969 success, or \NULL{} on failure. The operation is done \emph{in-place}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1970 when \var{o1} supports it. This is the equivalent of the Python
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1971 statement \samp{\var{o1} \textasciicircum= \var{o2}}.
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1972 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1973
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	1974 \begin{cfuncdesc}{PyObject}{PyNumber_InPlaceOr}{PyObject o1, PyObject *o2}
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1975 Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1976 \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1977 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	1978 \samp{\var{o1} \|= \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1979 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1980
14769 aa18e5239b46 PyNumber_Coerce() returns an int, not a PyObject . Fred Drake <fdrake@acm.org>* parents: 14736 diff changeset	1981 \begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject p1, PyObject p2}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1982 This function takes the addresses of two variables of type
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1983 \ctype{PyObject}. If the objects pointed to by \code{\var{p1}} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1984 \code{*\var{p2}} have the same type, increment their reference count
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1985 and return \code{0} (success). If the objects can be converted to a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1986 common numeric type, replace \code{p1} and \code{p2} by their
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1987 converted value (with 'new' reference counts), and return \code{0}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1988 If no conversion is possible, or if some other error occurs, return
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1989 \code{-1} (failure) and don't increment the reference counts. The
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1990 call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1991 statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1992 \bifuncindex{coerce}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1993 \end{cfuncdesc}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1994
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1995 \begin{cfuncdesc}{PyObject}{PyNumber_Int}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	1996 Returns the \var{o} converted to an integer object on success, or
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	1997 \NULL{} on failure. This is the equivalent of the Python
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1998 expression \samp{int(\var{o})}.\bifuncindex{int}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	1999 \end{cfuncdesc}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2000
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2001 \begin{cfuncdesc}{PyObject}{PyNumber_Long}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2002 Returns the \var{o} converted to a long integer object on success,
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2003 or \NULL{} on failure. This is the equivalent of the Python
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2004 expression \samp{long(\var{o})}.\bifuncindex{long}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2005 \end{cfuncdesc}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2006
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2007 \begin{cfuncdesc}{PyObject}{PyNumber_Float}{PyObject o}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2008 Returns the \var{o} converted to a float object on success, or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2009 \NULL{} on failure. This is the equivalent of the Python expression
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2010 \samp{float(\var{o})}.\bifuncindex{float}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2011 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2012
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2013
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2014 \section{Sequence Protocol \label{sequence}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2015
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2016 \begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2017 Return \code{1} if the object provides sequence protocol, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2018 \code{0} otherwise. This function always succeeds.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2019 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2020
17307 288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an Fred Drake <fdrake@acm.org> parents: 17242 diff changeset	2021 \begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2022 Returns the number of objects in sequence \var{o} on success, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2023 \code{-1} on failure. For objects that do not provide sequence
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2024 protocol, this is equivalent to the Python expression
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2025 \samp{len(\var{o})}.\bifuncindex{len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2026 \end{cfuncdesc}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2027
17307 288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an Fred Drake <fdrake@acm.org> parents: 17242 diff changeset	2028 \begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o}
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an Fred Drake <fdrake@acm.org> parents: 17242 diff changeset	2029 Alternate name for \cfunction{PySequence_Size()}.
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an Fred Drake <fdrake@acm.org> parents: 17242 diff changeset	2030 \end{cfuncdesc}
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an Fred Drake <fdrake@acm.org> parents: 17242 diff changeset	2031
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2032 \begin{cfuncdesc}{PyObject}{PySequence_Concat}{PyObject o1, PyObject *o2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2033 Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2034 failure. This is the equivalent of the Python
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2035 expression \samp{\var{o1} + \var{o2}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2036 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2037
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2038
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2039 \begin{cfuncdesc}{PyObject}{PySequence_Repeat}{PyObject o, int count}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2040 Return the result of repeating sequence object
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2041 \var{o} \var{count} times, or \NULL{} on failure. This is the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2042 equivalent of the Python expression \samp{\var{o} * \var{count}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2043 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2044
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	2045 \begin{cfuncdesc}{PyObject}{PySequence_InPlaceConcat}{PyObject o1,
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	2046 PyObject *o2}
14528 7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2047 Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2048 failure. The operation is done \emph{in-place} when \var{o1} supports it.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2049 This is the equivalent of the Python expression \samp{\var{o1} += \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2050 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2051
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2052
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2053 \begin{cfuncdesc}{PyObject}{PySequence_InPlaceRepeat}{PyObject o, int count}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2054 Return the result of repeating sequence object \var{o} \var{count} times, or
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2055 \NULL{} on failure. The operation is done \emph{in-place} when \var{o}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2056 supports it. This is the equivalent of the Python expression \samp{\var{o}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2057 *= \var{count}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2058 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>: Fred Drake <fdrake@acm.org> parents: 14526 diff changeset	2059
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2060
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2061 \begin{cfuncdesc}{PyObject}{PySequence_GetItem}{PyObject o, int i}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2062 Return the \var{i}th element of \var{o}, or \NULL{} on failure. This
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2063 is the equivalent of the Python expression \samp{\var{o}[\var{i}]}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2064 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2065
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2066
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2067 \begin{cfuncdesc}{PyObject}{PySequence_GetSlice}{PyObject o, int i1, int i2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2068 Return the slice of sequence object \var{o} between \var{i1} and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2069 \var{i2}, or \NULL{} on failure. This is the equivalent of the Python
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2070 expression \samp{\var{o}[\var{i1}:\var{i2}]}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2071 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2072
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2073
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2074 \begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject o, int i, PyObject v}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2075 Assign object \var{v} to the \var{i}th element of \var{o}.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2076 Returns \code{-1} on failure. This is the equivalent of the Python
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2077 statement \samp{\var{o}[\var{i}] = \var{v}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2078 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2079
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2080 \begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	2081 Delete the \var{i}th element of object \var{o}. Returns
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2082 \code{-1} on failure. This is the equivalent of the Python
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2083 statement \samp{del \var{o}[\var{i}]}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2084 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2085
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2086 \begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2087 int i2, PyObject *v}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2088 Assign the sequence object \var{v} to the slice in sequence
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2089 object \var{o} from \var{i1} to \var{i2}. This is the equivalent of
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2090 the Python statement \samp{\var{o}[\var{i1}:\var{i2}] = \var{v}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2091 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2092
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2093 \begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2094 Delete the slice in sequence object \var{o} from \var{i1} to \var{i2}.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2095 Returns \code{-1} on failure. This is the equivalent of the Python
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2096 statement \samp{del \var{o}[\var{i1}:\var{i2}]}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2097 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2098
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2099 \begin{cfuncdesc}{PyObject}{PySequence_Tuple}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2100 Returns the \var{o} as a tuple on success, and \NULL{} on failure.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2101 This is equivalent to the Python expression \samp{tuple(\var{o})}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2102 \bifuncindex{tuple}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2103 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2104
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2105 \begin{cfuncdesc}{int}{PySequence_Count}{PyObject o, PyObject value}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2106 Return the number of occurrences of \var{value} in \var{o}, that is,
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2107 return the number of keys for which \code{\var{o}[\var{key}] ==
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2108 \var{value}}. On failure, return \code{-1}. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2109 the Python expression \samp{\var{o}.count(\var{value})}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2110 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2111
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2112 \begin{cfuncdesc}{int}{PySequence_Contains}{PyObject o, PyObject value}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2113 Determine if \var{o} contains \var{value}. If an item in \var{o} is
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2114 equal to \var{value}, return \code{1}, otherwise return \code{0}. On
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2115 error, return \code{-1}. This is equivalent to the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2116 \samp{\var{value} in \var{o}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2117 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2118
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2119 \begin{cfuncdesc}{int}{PySequence_Index}{PyObject o, PyObject value}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2120 Return the first index \var{i} for which \code{\var{o}[\var{i}] ==
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2121 \var{value}}. On error, return \code{-1}. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2122 the Python expression \samp{\var{o}.index(\var{value})}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2123 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2124
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2125 \begin{cfuncdesc}{PyObject}{PySequence_List}{PyObject o}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2126 Return a list object with the same contents as the arbitrary sequence
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2127 \var{o}. The returned list is guaranteed to be new.
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2128 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2129
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2130 \begin{cfuncdesc}{PyObject}{PySequence_Tuple}{PyObject o}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2131 Return a tuple object with the same contents as the arbitrary sequence
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2132 \var{o}. If \var{o} is a tuple, a new reference will be returned,
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2133 otherwise a tuple will be constructed with the appropriate contents.
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2134 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	2135
7493 6857acbe2e74 Added \label{}s for logical addressing. Fred Drake <fdrake@acm.org> parents: 7467 diff changeset	2136
14519 7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2137 \begin{cfuncdesc}{PyObject}{PySequence_Fast}{PyObject o, const char *m}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2138 Returns the sequence \var{o} as a tuple, unless it is already a
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2139 tuple or list, in which case \var{o} is returned. Use
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2140 \cfunction{PySequence_Fast_GET_ITEM()} to access the members of the
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2141 result. Returns \NULL{} on failure. If the object is not a sequence,
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2142 raises \exception{TypeError} with \var{m} as the message text.
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2143 \end{cfuncdesc}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2144
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2145 \begin{cfuncdesc}{PyObject}{PySequence_Fast_GET_ITEM}{PyObject o, int i}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2146 Return the \var{i}th element of \var{o}, assuming that \var{o} was
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2147 returned by \cfunction{PySequence_Fast()}, and that \var{i} is within
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2148 bounds. The caller is expected to get the length of the sequence by
18000 ec9343ad1e60 Users of PySequence_GET_FAST() should get the length of the sequence using Fred Drake <fdrake@acm.org> parents: 17981 diff changeset	2149 calling \cfunction{PySequence_Size()} on \var{o}, since lists and tuples
14519 7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2150 are guaranteed to always return their true length.
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2151 \end{cfuncdesc}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2152
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM(). Fred Drake <fdrake@acm.org> parents: 14347 diff changeset	2153
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2154 \section{Mapping Protocol \label{mapping}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2155
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2156 \begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2157 Return \code{1} if the object provides mapping protocol, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2158 \code{0} otherwise. This function always succeeds.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2159 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2160
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2161
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2162 \begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2163 Returns the number of keys in object \var{o} on success, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2164 \code{-1} on failure. For objects that do not provide mapping
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2165 protocol, this is equivalent to the Python expression
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2166 \samp{len(\var{o})}.\bifuncindex{len}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2167 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2168
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2169
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2170 \begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject o, char key}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2171 Remove the mapping for object \var{key} from the object \var{o}.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2172 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2173 the Python statement \samp{del \var{o}[\var{key}]}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2174 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2175
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2176
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2177 \begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject o, PyObject key}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2178 Remove the mapping for object \var{key} from the object \var{o}.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2179 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2180 the Python statement \samp{del \var{o}[\var{key}]}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2181 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2182
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2183
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2184 \begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject o, char key}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2185 On success, return \code{1} if the mapping object has the key
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2186 \var{key} and \code{0} otherwise. This is equivalent to the Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2187 expression \samp{\var{o}.has_key(\var{key})}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2188 This function always succeeds.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2189 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2190
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2191
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2192 \begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject o, PyObject key}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2193 Return \code{1} if the mapping object has the key \var{key} and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2194 \code{0} otherwise. This is equivalent to the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2195 \samp{\var{o}.has_key(\var{key})}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2196 This function always succeeds.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2197 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2198
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2199
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2200 \begin{cfuncdesc}{PyObject}{PyMapping_Keys}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2201 On success, return a list of the keys in object \var{o}. On
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2202 failure, return \NULL{}. This is equivalent to the Python
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2203 expression \samp{\var{o}.keys()}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2204 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2205
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2206
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2207 \begin{cfuncdesc}{PyObject}{PyMapping_Values}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2208 On success, return a list of the values in object \var{o}. On
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2209 failure, return \NULL{}. This is equivalent to the Python
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2210 expression \samp{\var{o}.values()}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2211 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2212
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2213
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2214 \begin{cfuncdesc}{PyObject}{PyMapping_Items}{PyObject o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2215 On success, return a list of the items in object \var{o}, where
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2216 each item is a tuple containing a key-value pair. On
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2217 failure, return \NULL{}. This is equivalent to the Python
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2218 expression \samp{\var{o}.items()}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2219 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2220
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2221
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2222 \begin{cfuncdesc}{PyObject}{PyMapping_GetItemString}{PyObject o, char *key}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2223 Return element of \var{o} corresponding to the object \var{key} or
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2224 \NULL{} on failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2225 \samp{\var{o}[\var{key}]}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2226 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2227
17695 1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2228 \begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject o, char key,
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2229 PyObject *v}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2230 Map the object \var{key} to the value \var{v} in object \var{o}.
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2231 Returns \code{-1} on failure. This is the equivalent of the Python
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	2232 statement \samp{\var{o}[\var{key}] = \var{v}}.
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2233 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2234
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2235
17695 1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2236 \section{Iterator Protocol \label{iterator}}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2237
17696 ffc2923bad1a Hmm... better add a version annotation for the Iterator Protocol section. Fred Drake <fdrake@acm.org> parents: 17695 diff changeset	2238 \versionadded{2.2}
ffc2923bad1a Hmm... better add a version annotation for the Iterator Protocol section. Fred Drake <fdrake@acm.org> parents: 17695 diff changeset	2239
17695 1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2240 There are only a couple of functions specifically for working with
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2241 iterators.
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2242
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2243 \begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2244 Return true if the object \var{o} supports the iterator protocol.
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2245 \end{cfuncdesc}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2246
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2247 \begin{cfuncdesc}{PyObject}{PyIter_Next}{PyObject o}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2248 Return the next value from the iteration \var{o}. If the object is
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2249 an iterator, this retrieves the next value from the iteration, and
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2250 returns \NULL{} with no exception set if there are no remaining
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2251 items. If the object is not an iterator, \exception{TypeError} is
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2252 raised, or if there is an error in retrieving the item, returns
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2253 \NULL{} and passes along the exception.
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2254 \end{cfuncdesc}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2255
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2256 To write a loop which iterates over an iterator, the C code should
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2257 look something like this:
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2258
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2259 \begin{verbatim}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2260 PyObject *iterator = ...;
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2261 PyObject *item;
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2262
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2263 while (item = PyIter_Next(iter)) {
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2264 /* do something with item */
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2265 }
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2266 if (PyErr_Occurred()) {
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2267 /* propogate error */
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2268 }
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2269 else {
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2270 /* continue doing useful work */
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2271 }
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2272 \end{verbatim}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2273
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next(). Fred Drake <fdrake@acm.org> parents: 17618 diff changeset	2274
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2275 \chapter{Concrete Objects Layer \label{concrete}}
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2276
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2277 The functions in this chapter are specific to certain Python object
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2278 types. Passing them an object of the wrong type is not a good idea;
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2279 if you receive an object from a Python program and you are not sure
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	2280 that it has the right type, you must perform a type check first;
16053 aca05d75d232 Fixed a bunch of typos caught by Gilles Civario. Fred Drake <fdrake@acm.org> parents: 15953 diff changeset	2281 for example, to check that an object is a dictionary, use
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2282 \cfunction{PyDict_Check()}. The chapter is structured like the
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2283 ``family tree'' of Python object types.
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2284
15300 0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2285 \strong{Warning:}
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2286 While the functions described in this chapter carefully check the type
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2287 of the objects which are passed in, many of them do not check for
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2288 \NULL{} being passed instead of a valid object. Allowing \NULL{} to
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2289 be passed in can cause memory access violations and immediate
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2290 termination of the interpreter.
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2291
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2292
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2293 \section{Fundamental Objects \label{fundamental}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2294
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2295 This section describes Python type objects and the singleton object
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2296 \code{None}.
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2297
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2298
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2299 \subsection{Type Objects \label{typeObjects}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2300
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2301 \obindex{type}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2302 \begin{ctypedesc}{PyTypeObject}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2303 The C structure of the objects used to describe built-in types.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2304 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2305
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2306 \begin{cvardesc}{PyObject*}{PyType_Type}
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2307 This is the type object for type objects; it is the same object as
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2308 \code{types.TypeType} in the Python layer.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2309 \withsubitem{(in module types)}{\ttindex{TypeType}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2310 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2311
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2312 \begin{cfuncdesc}{int}{PyType_Check}{PyObject *o}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2313 Returns true is the object \var{o} is a type object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2314 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2315
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2316 \begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2317 Returns true if the type object \var{o} sets the feature
16439 d557ff0a2f6c Remove an now-false statement about there being only one type flag Fred Drake <fdrake@acm.org> parents: 16318 diff changeset	2318 \var{feature}. Type features are denoted by single bit flags.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2319 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2320
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2321
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2322 \subsection{The None Object \label{noneObject}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2323
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2324 \obindex{None@\texttt{None}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2325 Note that the \ctype{PyTypeObject} for \code{None} is not directly
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2326 exposed in the Python/C API. Since \code{None} is a singleton,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2327 testing for object identity (using \samp{==} in C) is sufficient.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2328 There is no \cfunction{PyNone_Check()} function for the same reason.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2329
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2330 \begin{cvardesc}{PyObject*}{Py_None}
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2331 The Python \code{None} object, denoting lack of value. This object has
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2332 no methods.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2333 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2334
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2335
18481 795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2336 \section{Numeric Objects \label{numericObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2337
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2338 \obindex{numeric}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2339
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2340
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2341 \subsection{Plain Integer Objects \label{intObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2342
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2343 \obindex{integer}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2344 \begin{ctypedesc}{PyIntObject}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2345 This subtype of \ctype{PyObject} represents a Python integer object.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2346 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2347
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2348 \begin{cvardesc}{PyTypeObject}{PyInt_Type}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2349 This instance of \ctype{PyTypeObject} represents the Python plain
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2350 integer type. This is the same object as \code{types.IntType}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2351 \withsubitem{(in modules types)}{\ttindex{IntType}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2352 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2353
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2354 \begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2355 Returns true if \var{o} is of type \cdata{PyInt_Type}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2356 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2357
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2358 \begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2359 Creates a new integer object with a value of \var{ival}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2360
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2361 The current implementation keeps an array of integer objects for all
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2362 integers between \code{-1} and \code{100}, when you create an int in
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2363 that range you actually just get back a reference to the existing
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2364 object. So it should be possible to change the value of \code{1}. I
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2365 suspect the behaviour of Python in this case is undefined. :-)
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2366 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2367
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2368 \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2369 Will first attempt to cast the object to a \ctype{PyIntObject}, if
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2370 it is not already one, and then return its value.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2371 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2372
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2373 \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2374 Returns the value of the object \var{io}. No error checking is
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2375 performed.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2376 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2377
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2378 \begin{cfuncdesc}{long}{PyInt_GetMax}{}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2379 Returns the system's idea of the largest integer it can handle
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2380 (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2381 header files).
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2382 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2383
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2384
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2385 \subsection{Long Integer Objects \label{longObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2386
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2387 \obindex{long integer}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2388 \begin{ctypedesc}{PyLongObject}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2389 This subtype of \ctype{PyObject} represents a Python long integer
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2390 object.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2391 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2392
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2393 \begin{cvardesc}{PyTypeObject}{PyLong_Type}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2394 This instance of \ctype{PyTypeObject} represents the Python long
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2395 integer type. This is the same object as \code{types.LongType}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2396 \withsubitem{(in modules types)}{\ttindex{LongType}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2397 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2398
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2399 \begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2400 Returns true if its argument is a \ctype{PyLongObject}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2401 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2402
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2403 \begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2404 Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{} on
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2405 failure.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2406 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2407
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2408 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2409 Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2410 long}, or \NULL{} on failure.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2411 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2412
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2413 \begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2414 Returns a new \ctype{PyLongObject} object from the integer part of
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2415 \var{v}, or \NULL{} on failure.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2416 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2417
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2418 \begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2419 Returns a C \ctype{long} representation of the contents of
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2420 \var{pylong}. If \var{pylong} is greater than
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2421 \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2422 raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2423 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2424
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2425 \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2426 Returns a C \ctype{unsigned long} representation of the contents of
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2427 \var{pylong}. If \var{pylong} is greater than
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2428 \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2429 is raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2430 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2431
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2432 \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2433 Returns a C \ctype{double} representation of the contents of \var{pylong}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2434 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2435
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2436 \begin{cfuncdesc}{PyObject}{PyLong_FromString}{char str, char **pend,
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2437 int base}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2438 Return a new \ctype{PyLongObject} based on the string value in
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2439 \var{str}, which is interpreted according to the radix in \var{base}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2440 If \var{pend} is non-\NULL, \code{*\var{pend}} will point to the first
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2441 character in \var{str} which follows the representation of the
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2442 number. If \var{base} is \code{0}, the radix will be determined base
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2443 on the leading characters of \var{str}: if \var{str} starts with
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2444 \code{'0x'} or \code{'0X'}, radix 16 will be used; if \var{str} starts
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2445 with \code{'0'}, radix 8 will be used; otherwise radix 10 will be
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2446 used. If \var{base} is not \code{0}, it must be between \code{2} and
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2447 \code{36}, inclusive. Leading spaces are ignored. If there are no
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2448 digits, \exception{ValueError} will be raised.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2449 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2450
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2451
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2452 \subsection{Floating Point Objects \label{floatObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2453
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2454 \obindex{floating point}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2455 \begin{ctypedesc}{PyFloatObject}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2456 This subtype of \ctype{PyObject} represents a Python floating point
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2457 object.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2458 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2459
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2460 \begin{cvardesc}{PyTypeObject}{PyFloat_Type}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2461 This instance of \ctype{PyTypeObject} represents the Python floating
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2462 point type. This is the same object as \code{types.FloatType}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2463 \withsubitem{(in modules types)}{\ttindex{FloatType}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2464 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2465
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2466 \begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2467 Returns true if its argument is a \ctype{PyFloatObject}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2468 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2469
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2470 \begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2471 Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2472 failure.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2473 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2474
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2475 \begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2476 Returns a C \ctype{double} representation of the contents of \var{pyfloat}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2477 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2478
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2479 \begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2480 Returns a C \ctype{double} representation of the contents of
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2481 \var{pyfloat}, but without error checking.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2482 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2483
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2484
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2485 \subsection{Complex Number Objects \label{complexObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2486
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2487 \obindex{complex number}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2488 Python's complex number objects are implemented as two distinct types
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2489 when viewed from the C API: one is the Python object exposed to
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2490 Python programs, and the other is a C structure which represents the
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2491 actual complex number value. The API provides functions for working
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2492 with both.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2493
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2494 \subsubsection{Complex Numbers as C Structures}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2495
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2496 Note that the functions which accept these structures as parameters
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2497 and return them as results do so \emph{by value} rather than
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2498 dereferencing them through pointers. This is consistent throughout
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2499 the API.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2500
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2501 \begin{ctypedesc}{Py_complex}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2502 The C structure which corresponds to the value portion of a Python
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2503 complex number object. Most of the functions for dealing with complex
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2504 number objects use structures of this type as input or output values,
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2505 as appropriate. It is defined as:
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2506
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2507 \begin{verbatim}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2508 typedef struct {
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2509 double real;
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2510 double imag;
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2511 } Py_complex;
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2512 \end{verbatim}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2513 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2514
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2515 \begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2516 Return the sum of two complex numbers, using the C
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2517 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2518 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2519
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2520 \begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2521 Return the difference between two complex numbers, using the C
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2522 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2523 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2524
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2525 \begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2526 Return the negation of the complex number \var{complex}, using the C
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2527 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2528 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2529
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2530 \begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2531 Return the product of two complex numbers, using the C
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2532 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2533 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2534
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2535 \begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2536 Py_complex divisor}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2537 Return the quotient of two complex numbers, using the C
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2538 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2539 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2540
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2541 \begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2542 Return the exponentiation of \var{num} by \var{exp}, using the C
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2543 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2544 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2545
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2546
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2547 \subsubsection{Complex Numbers as Python Objects}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2548
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2549 \begin{ctypedesc}{PyComplexObject}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2550 This subtype of \ctype{PyObject} represents a Python complex number object.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2551 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2552
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2553 \begin{cvardesc}{PyTypeObject}{PyComplex_Type}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2554 This instance of \ctype{PyTypeObject} represents the Python complex
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2555 number type.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2556 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2557
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2558 \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2559 Returns true if its argument is a \ctype{PyComplexObject}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2560 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2561
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2562 \begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2563 Create a new Python complex number object from a C
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2564 \ctype{Py_complex} value.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2565 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2566
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2567 \begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2568 Returns a new \ctype{PyComplexObject} object from \var{real} and \var{imag}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2569 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2570
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2571 \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2572 Returns the real part of \var{op} as a C \ctype{double}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2573 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2574
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2575 \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2576 Returns the imaginary part of \var{op} as a C \ctype{double}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2577 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2578
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2579 \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2580 Returns the \ctype{Py_complex} value of the complex number \var{op}.
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2581 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2582
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2583
795aa4590211 Move the section on concrete numeric objects before the section on Fred Drake <fdrake@acm.org> parents: 18447 diff changeset	2584
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2585 \section{Sequence Objects \label{sequenceObjects}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2586
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2587 \obindex{sequence}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2588 Generic operations on sequence objects were discussed in the previous
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2589 chapter; this section deals with the specific kinds of sequence
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2590 objects that are intrinsic to the Python language.
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2591
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2592
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	2593 \subsection{String Objects \label{stringObjects}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2594
15300 0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2595 These functions raise \exception{TypeError} when expecting a string
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2596 parameter and are called with a non-string parameter.
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2597
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2598 \obindex{string}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2599 \begin{ctypedesc}{PyStringObject}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	2600 This subtype of \ctype{PyObject} represents a Python string object.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2601 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2602
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2603 \begin{cvardesc}{PyTypeObject}{PyString_Type}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2604 This instance of \ctype{PyTypeObject} represents the Python string
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2605 type; it is the same object as \code{types.TypeType} in the Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2606 layer.\withsubitem{(in module types)}{\ttindex{StringType}}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2607 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2608
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2609 \begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
8057 5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes. Guido van Rossum <guido@python.org> parents: 8029 diff changeset	2610 Returns true if the object \var{o} is a string object.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2611 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2612
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2613 \begin{cfuncdesc}{PyObject}{PyString_FromString}{const char v}
8057 5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes. Guido van Rossum <guido@python.org> parents: 8029 diff changeset	2614 Returns a new string object with the value \var{v} on success, and
5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes. Guido van Rossum <guido@python.org> parents: 8029 diff changeset	2615 \NULL{} on failure.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2616 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2617
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2618 \begin{cfuncdesc}{PyObject}{PyString_FromStringAndSize}{const char v,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2619 int len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2620 Returns a new string object with the value \var{v} and length
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2621 \var{len} on success, and \NULL{} on failure. If \var{v} is \NULL{},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2622 the contents of the string are uninitialized.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2623 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2624
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2625 \begin{cfuncdesc}{int}{PyString_Size}{PyObject *string}
8057 5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes. Guido van Rossum <guido@python.org> parents: 8029 diff changeset	2626 Returns the length of the string in string object \var{string}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2627 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2628
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2629 \begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
15087 a13a2acbe214 Fix a couple of places where the descriptions of _GET_SIZE() macros said Fred Drake <fdrake@acm.org>* parents: 15038 diff changeset	2630 Macro form of \cfunction{PyString_Size()} but without error
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2631 checking.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2632 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2633
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2634 \begin{cfuncdesc}{char}{PyString_AsString}{PyObject string}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2635 Returns a null-terminated representation of the contents of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2636 \var{string}. The pointer refers to the internal buffer of
15300 0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2637 \var{string}, not a copy. The data must not be modified in any way,
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2638 unless the string was just created using
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2639 \code{PyString_FromStringAndSize(NULL, \var{size})}.
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2640 It must not be deallocated.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2641 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2642
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2643 \begin{cfuncdesc}{char}{PyString_AS_STRING}{PyObject string}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2644 Macro form of \cfunction{PyString_AsString()} but without error
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2645 checking.
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2646 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2647
14696 85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2648 \begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2649 char **buffer,
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2650 int *length}
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2651 Returns a null-terminated representation of the contents of the object
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2652 \var{obj} through the output variables \var{buffer} and \var{length}.
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2653
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2654 The function accepts both string and Unicode objects as input. For
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2655 Unicode objects it returns the default encoded version of the object.
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2656 If \var{length} is set to \NULL{}, the resulting buffer may not contain
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2657 null characters; if it does, the function returns -1 and a
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2658 TypeError is raised.
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2659
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2660 The buffer refers to an internal string buffer of \var{obj}, not a
15300 0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2661 copy. The data must not be modified in any way, unless the string was
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2662 just created using \code{PyString_FromStringAndSize(NULL,
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString() Fred Drake <fdrake@acm.org> parents: 15236 diff changeset	2663 \var{size})}. It must not be deallocated.
14696 85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2664 \end{cfuncdesc}
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize() Marc-André Lemburg <mal@egenix.com> parents: 14635 diff changeset	2665
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2666 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2667 PyObject *newpart}
10170 7cf97658cae7 Be explicit about the reference count of the original value of the Fred Drake <fdrake@acm.org> parents: 10163 diff changeset	2668 Creates a new string object in \var{*string} containing the
12200 42f21e47b486 Improve explanation of reference counts for PyString_Concat(). Fred Drake <fdrake@acm.org> parents: 12126 diff changeset	2669 contents of \var{newpart} appended to \var{string}; the caller will
42f21e47b486 Improve explanation of reference counts for PyString_Concat(). Fred Drake <fdrake@acm.org> parents: 12126 diff changeset	2670 own the new reference. The reference to the old value of \var{string}
42f21e47b486 Improve explanation of reference counts for PyString_Concat(). Fred Drake <fdrake@acm.org> parents: 12126 diff changeset	2671 will be stolen. If the new string
10170 7cf97658cae7 Be explicit about the reference count of the original value of the Fred Drake <fdrake@acm.org> parents: 10163 diff changeset	2672 cannot be created, the old reference to \var{string} will still be
7cf97658cae7 Be explicit about the reference count of the original value of the Fred Drake <fdrake@acm.org> parents: 10163 diff changeset	2673 discarded and the value of \var{*string} will be set to
7cf97658cae7 Be explicit about the reference count of the original value of the Fred Drake <fdrake@acm.org> parents: 10163 diff changeset	2674 \NULL{}; the appropriate exception will be set.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2675 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2676
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2677 \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2678 PyObject *newpart}
8057 5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes. Guido van Rossum <guido@python.org> parents: 8029 diff changeset	2679 Creates a new string object in \var{*string} containing the contents
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2680 of \var{newpart} appended to \var{string}. This version decrements
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2681 the reference count of \var{newpart}.
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2682 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2683
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2684 \begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **string, int newsize}
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2685 A way to resize a string object even though it is ``immutable''.
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2686 Only use this to build up a brand new string object; don't use this if
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2687 the string may already be known in other parts of the code.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2688 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2689
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2690 \begin{cfuncdesc}{PyObject}{PyString_Format}{PyObject format,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2691 PyObject *args}
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2692 Returns a new string object from \var{format} and \var{args}. Analogous
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	2693 to \code{\var{format} \%\ \var{args}}. The \var{args} argument must be
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2694 a tuple.
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2695 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2696
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2697 \begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **string}
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2698 Intern the argument \var{*string} in place. The argument must be the
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2699 address of a pointer variable pointing to a Python string object.
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2700 If there is an existing interned string that is the same as
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2701 \var{string}, it sets \var{string} to it (decrementing the reference
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2702 count of the old string object and incrementing the reference count of
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2703 the interned string object), otherwise it leaves \var{*string} alone
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2704 and interns it (incrementing its reference count). (Clarification:
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2705 even though there is a lot of talk about reference counts, think of
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	2706 this function as reference-count-neutral; you own the object after
068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	2707 the call if and only if you owned it before the call.)
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2708 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2709
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2710 \begin{cfuncdesc}{PyObject}{PyString_InternFromString}{const char v}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	2711 A combination of \cfunction{PyString_FromString()} and
068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	2712 \cfunction{PyString_InternInPlace()}, returning either a new string object
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2713 that has been interned, or a new (``owned'') reference to an earlier
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	2714 interned string object with the same value.
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2715 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	2716
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2717 \begin{cfuncdesc}{PyObject}{PyString_Decode}{const char s,
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2718 int size,
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2719 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2720 const char *errors}
17835 9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2721 Creates an object by decoding \var{size} bytes of the encoded
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2722 buffer \var{s} using the codec registered
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2723 for \var{encoding}. \var{encoding} and \var{errors} have the same meaning
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2724 as the parameters of the same name in the unicode() builtin
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2725 function. The codec to be used is looked up using the Python codec
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2726 registry. Returns \NULL{} in case an exception was raised by the
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2727 codec.
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2728 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2729
17835 9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2730 \begin{cfuncdesc}{PyObject}{PyString_AsDecodedObject}{PyObject str,
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2731 const char *encoding,
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2732 const char *errors}
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2733 Decodes a string object by passing it to the codec registered
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2734 for \var{encoding} and returns the result as Python
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2735 object. \var{encoding} and \var{errors} have the same meaning as the
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2736 parameters of the same name in the string .encode() method. The codec
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2737 to be used is looked up using the Python codec registry. Returns
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2738 \NULL{} in case an exception was raised by the codec.
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2739 \end{cfuncdesc}
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2740
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2741 \begin{cfuncdesc}{PyObject}{PyString_Encode}{const char s,
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2742 int size,
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2743 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2744 const char *errors}
17835 9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2745 Encodes the \ctype{char} buffer of the given size by passing it to
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2746 the codec registered for \var{encoding} and returns a Python object.
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2747 \var{encoding} and \var{errors} have the same
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2748 meaning as the parameters of the same name in the string .encode()
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2749 method. The codec to be used is looked up using the Python codec
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2750 registry. Returns \NULL{} in case an exception was raised by the
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2751 codec.
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2752 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2753
17835 9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2754 \begin{cfuncdesc}{PyObject}{PyString_AsEncodedObject}{PyObject str,
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2755 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2756 const char *errors}
17835 9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2757 Encodes a string object using the codec registered
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly Marc-André Lemburg <mal@egenix.com> parents: 17696 diff changeset	2758 for \var{encoding} and returns the result as Python
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2759 object. \var{encoding} and \var{errors} have the same meaning as the
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2760 parameters of the same name in the string .encode() method. The codec
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2761 to be used is looked up using the Python codec registry. Returns
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2762 \NULL{} in case an exception was raised by the codec.
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2763 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2764
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	2765
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2766 \subsection{Unicode Objects \label{unicodeObjects}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2767 \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2768
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2769 %--- Unicode Type -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2770
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2771 These are the basic Unicode object types used for the Unicode
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2772 implementation in Python:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2773
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2774 \begin{ctypedesc}{Py_UNICODE}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2775 This type represents a 16-bit unsigned storage type which is used by
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2776 Python internally as basis for holding Unicode ordinals. On platforms
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2777 where \ctype{wchar_t} is available and also has 16-bits,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2778 \ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2779 native platform compatibility. On all other platforms,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2780 \ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2781 \end{ctypedesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2782
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2783 \begin{ctypedesc}{PyUnicodeObject}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2784 This subtype of \ctype{PyObject} represents a Python Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2785 \end{ctypedesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2786
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2787 \begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2788 This instance of \ctype{PyTypeObject} represents the Python Unicode type.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2789 \end{cvardesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2790
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2791 %--- These are really C macros... is there a macrodesc TeX macro ?
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2792
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2793 The following APIs are really C macros and can be used to do fast
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2794 checks and to access internal read-only data of Unicode objects:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2795
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2796 \begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2797 Returns true if the object \var{o} is a Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2798 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2799
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2800 \begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2801 Returns the size of the object. o has to be a
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2802 PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2803 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2804
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2805 \begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2806 Returns the size of the object's internal buffer in bytes. o has to be
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2807 a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2808 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2809
12932 1fa7c119b7a5 Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support. Fred Drake <fdrake@acm.org> parents: 12930 diff changeset	2810 \begin{cfuncdesc}{Py_UNICODE}{PyUnicode_AS_UNICODE}{PyObject o}
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2811 Returns a pointer to the internal Py_UNICODE buffer of the object. o
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2812 has to be a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2813 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2814
12932 1fa7c119b7a5 Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support. Fred Drake <fdrake@acm.org> parents: 12930 diff changeset	2815 \begin{cfuncdesc}{const char}{PyUnicode_AS_DATA}{PyObject o}
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2816 Returns a (const char *) pointer to the internal buffer of the object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2817 o has to be a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2818 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2819
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2820 % --- Unicode character properties ---------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2821
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2822 Unicode provides many different character properties. The most often
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2823 needed ones are available through these macros which are mapped to C
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2824 functions depending on the Python configuration.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2825
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2826 \begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2827 Returns 1/0 depending on whether \var{ch} is a whitespace character.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2828 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2829
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2830 \begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2831 Returns 1/0 depending on whether \var{ch} is a lowercase character.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2832 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2833
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2834 \begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
13321 ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 13217 diff changeset	2835 Returns 1/0 depending on whether \var{ch} is an uppercase character.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2836 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2837
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2838 \begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2839 Returns 1/0 depending on whether \var{ch} is a titlecase character.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2840 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2841
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2842 \begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2843 Returns 1/0 depending on whether \var{ch} is a linebreak character.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2844 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2845
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2846 \begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2847 Returns 1/0 depending on whether \var{ch} is a decimal character.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2848 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2849
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2850 \begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2851 Returns 1/0 depending on whether \var{ch} is a digit character.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2852 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2853
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2854 \begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2855 Returns 1/0 depending on whether \var{ch} is a numeric character.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2856 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2857
13321 ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 13217 diff changeset	2858 \begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 13217 diff changeset	2859 Returns 1/0 depending on whether \var{ch} is an alphabetic character.
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 13217 diff changeset	2860 \end{cfuncdesc}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 13217 diff changeset	2861
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 13217 diff changeset	2862 \begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 13217 diff changeset	2863 Returns 1/0 depending on whether \var{ch} is an alphanumeric character.
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 13217 diff changeset	2864 \end{cfuncdesc}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 13217 diff changeset	2865
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2866 These APIs can be used for fast direct character conversions:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2867
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2868 \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2869 Returns the character \var{ch} converted to lower case.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2870 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2871
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2872 \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2873 Returns the character \var{ch} converted to upper case.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2874 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2875
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2876 \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2877 Returns the character \var{ch} converted to title case.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2878 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2879
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2880 \begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2881 Returns the character \var{ch} converted to a decimal positive integer.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2882 Returns -1 in case this is not possible. Does not raise exceptions.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2883 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2884
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2885 \begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2886 Returns the character \var{ch} converted to a single digit integer.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2887 Returns -1 in case this is not possible. Does not raise exceptions.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2888 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2889
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2890 \begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2891 Returns the character \var{ch} converted to a (positive) double.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2892 Returns -1.0 in case this is not possible. Does not raise exceptions.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2893 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2894
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2895 % --- Plain Py_UNICODE ---------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2896
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2897 To create Unicode objects and access their basic sequence properties,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2898 use these APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2899
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2900 \begin{cfuncdesc}{PyObject}{PyUnicode_FromUnicode}{const Py_UNICODE u,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2901 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2902
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2903 Create a Unicode Object from the Py_UNICODE buffer \var{u} of the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2904 given size. \var{u} may be \NULL{} which causes the contents to be
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2905 undefined. It is the user's responsibility to fill in the needed data.
17618 b44ba7c01217 This patch originated from an idea by Martin v. Loewis who submitted a Marc-André Lemburg <mal@egenix.com> parents: 17504 diff changeset	2906 The buffer is copied into the new object. If the buffer is not \NULL{},
b44ba7c01217 This patch originated from an idea by Martin v. Loewis who submitted a Marc-André Lemburg <mal@egenix.com> parents: 17504 diff changeset	2907 the return value might be a shared object. Therefore, modification of
b44ba7c01217 This patch originated from an idea by Martin v. Loewis who submitted a Marc-André Lemburg <mal@egenix.com> parents: 17504 diff changeset	2908 the resulting Unicode Object is only allowed when \var{u} is \NULL{}.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2909 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2910
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	2911 \begin{cfuncdesc}{Py_UNICODE}{PyUnicode_AsUnicode}{PyObject unicode}
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2912 Return a read-only pointer to the Unicode object's internal
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2913 \ctype{Py_UNICODE} buffer.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2914 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2915
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2916 \begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2917 Return the length of the Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2918 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2919
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2920 \begin{cfuncdesc}{PyObject}{PyUnicode_FromEncodedObject}{PyObject obj,
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2921 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2922 const char *errors}
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2923
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2924 Coerce an encoded object obj to an Unicode object and return a
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2925 reference with incremented refcount.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2926
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2927 Coercion is done in the following way:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2928 \begin{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2929 \item Unicode objects are passed back as-is with incremented
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2930 refcount. Note: these cannot be decoded; passing a non-NULL
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2931 value for encoding will result in a TypeError.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2932
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2933 \item String and other char buffer compatible objects are decoded
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2934 according to the given encoding and using the error handling
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2935 defined by errors. Both can be NULL to have the interface use
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2936 the default values (see the next section for details).
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2937
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2938 \item All other objects cause an exception.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2939 \end{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2940 The API returns NULL in case of an error. The caller is responsible
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2941 for decref'ing the returned objects.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2942 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2943
13404 4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2944 \begin{cfuncdesc}{PyObject}{PyUnicode_FromObject}{PyObject obj}
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2945
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2946 Shortcut for PyUnicode_FromEncodedObject(obj, NULL, ``strict'')
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2947 which is used throughout the interpreter whenever coercion to
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2948 Unicode is needed.
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2949 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs. Marc-André Lemburg <mal@egenix.com> parents: 13321 diff changeset	2950
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2951 % --- wchar_t support for platforms which support it ---------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2952
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2953 If the platform supports \ctype{wchar_t} and provides a header file
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2954 wchar.h, Python can interface directly to this type using the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2955 following functions. Support is optimized if Python's own
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2956 \ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2957
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2958 \begin{cfuncdesc}{PyObject}{PyUnicode_FromWideChar}{const wchar_t w,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2959 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2960 Create a Unicode Object from the \ctype{whcar_t} buffer \var{w} of the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2961 given size. Returns \NULL{} on failure.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2962 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2963
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2964 \begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2965 wchar_t *w,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2966 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2967 Copies the Unicode Object contents into the \ctype{whcar_t} buffer
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2968 \var{w}. At most \var{size} \ctype{whcar_t} characters are copied.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2969 Returns the number of \ctype{whcar_t} characters copied or -1 in case
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2970 of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2971 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2972
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2973
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2974 \subsubsection{Builtin Codecs \label{builtinCodecs}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2975
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2976 Python provides a set of builtin codecs which are written in C
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2977 for speed. All of these codecs are directly usable via the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2978 following functions.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2979
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2980 Many of the following APIs take two arguments encoding and
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2981 errors. These parameters encoding and errors have the same semantics
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2982 as the ones of the builtin unicode() Unicode object constructor.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2983
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2984 Setting encoding to NULL causes the default encoding to be used which
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2985 is UTF-8.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2986
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2987 Error handling is set by errors which may also be set to NULL meaning
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2988 to use the default handling defined for the codec. Default error
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2989 handling for all builtin codecs is ``strict'' (ValueErrors are raised).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2990
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2991 The codecs all use a similar interface. Only deviation from the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2992 following generic ones are documented for simplicity.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2993
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2994 % --- Generic Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2995
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2996 These are the generic codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2997
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2998 \begin{cfuncdesc}{PyObject}{PyUnicode_Decode}{const char s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	2999 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3000 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3001 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3002 Create a Unicode object by decoding \var{size} bytes of the encoded
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3003 string \var{s}. \var{encoding} and \var{errors} have the same meaning
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3004 as the parameters of the same name in the unicode() builtin
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3005 function. The codec to be used is looked up using the Python codec
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3006 registry. Returns \NULL{} in case an exception was raised by the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3007 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3008 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3009
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3010 \begin{cfuncdesc}{PyObject}{PyUnicode_Encode}{const Py_UNICODE s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3011 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3012 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3013 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3014 Encodes the \ctype{Py_UNICODE} buffer of the given size and returns a
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3015 Python string object. \var{encoding} and \var{errors} have the same
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3016 meaning as the parameters of the same name in the Unicode .encode()
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3017 method. The codec to be used is looked up using the Python codec
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3018 registry. Returns \NULL{} in case an exception was raised by the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3019 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3020 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3021
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3022 \begin{cfuncdesc}{PyObject}{PyUnicode_AsEncodedString}{PyObject unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3023 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3024 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3025 Encodes a Unicode object and returns the result as Python string
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3026 object. \var{encoding} and \var{errors} have the same meaning as the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3027 parameters of the same name in the Unicode .encode() method. The codec
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3028 to be used is looked up using the Python codec registry. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3029 \NULL{} in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3030 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3031
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3032 % --- UTF-8 Codecs -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3033
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3034 These are the UTF-8 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3035
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3036 \begin{cfuncdesc}{PyObject}{PyUnicode_DecodeUTF8}{const char s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3037 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3038 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3039 Creates a Unicode object by decoding \var{size} bytes of the UTF-8
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3040 encoded string \var{s}. Returns \NULL{} in case an exception was
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3041 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3042 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3043
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3044 \begin{cfuncdesc}{PyObject}{PyUnicode_EncodeUTF8}{const Py_UNICODE s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3045 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3046 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3047 Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3048 and returns a Python string object. Returns \NULL{} in case an
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3049 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3050 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3051
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3052 \begin{cfuncdesc}{PyObject}{PyUnicode_AsUTF8String}{PyObject unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3053 Encodes a Unicode objects using UTF-8 and returns the result as Python
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3054 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3055 \NULL{} in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3056 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3057
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3058 % --- UTF-16 Codecs ------------------------------------------------------ */
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3059
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3060 These are the UTF-16 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3061
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3062 \begin{cfuncdesc}{PyObject}{PyUnicode_DecodeUTF16}{const char s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3063 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3064 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3065 int *byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3066 Decodes \var{length} bytes from a UTF-16 encoded buffer string and
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3067 returns the corresponding Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3068
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3069 \var{errors} (if non-NULL) defines the error handling. It defaults
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3070 to ``strict''.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3071
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3072 If \var{byteorder} is non-\NULL{}, the decoder starts decoding using
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3073 the given byte order:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3074
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3075 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3076 *byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3077 *byteorder == 0: native order
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3078 *byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3079 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3080
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3081 and then switches according to all byte order marks (BOM) it finds in
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3082 the input data. BOM marks are not copied into the resulting Unicode
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3083 string. After completion, \var{*byteorder} is set to the current byte
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3084 order at the end of input data.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3085
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3086 If \var{byteorder} is \NULL{}, the codec starts in native order mode.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3087
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3088 Returns \NULL{} in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3089 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3090
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3091 \begin{cfuncdesc}{PyObject}{PyUnicode_EncodeUTF16}{const Py_UNICODE s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3092 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3093 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3094 int byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3095 Returns a Python string object holding the UTF-16 encoded value of the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3096 Unicode data in \var{s}.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3097
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	3098 If \var{byteorder} is not \code{0}, output is written according to the
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3099 following byte order:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3100
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3101 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3102 byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3103 byteorder == 0: native byte order (writes a BOM mark)
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3104 byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3105 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3106
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	3107 If byteorder is \code{0}, the output string will always start with the
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3108 Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3109 prepended.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3110
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3111 Note that \ctype{Py_UNICODE} data is being interpreted as UTF-16
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3112 reduced to UCS-2. This trick makes it possible to add full UTF-16
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3113 capabilities at a later point without comprimising the APIs.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3114
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3115 Returns \NULL{} in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3116 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3117
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3118 \begin{cfuncdesc}{PyObject}{PyUnicode_AsUTF16String}{PyObject unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3119 Returns a Python string using the UTF-16 encoding in native byte
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3120 order. The string always starts with a BOM mark. Error handling is
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3121 ``strict''. Returns \NULL{} in case an exception was raised by the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3122 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3123 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3124
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3125 % --- Unicode-Escape Codecs ----------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3126
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3127 These are the ``Unicode Esacpe'' codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3128
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3129 \begin{cfuncdesc}{PyObject}{PyUnicode_DecodeUnicodeEscape}{const char s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3130 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3131 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3132 Creates a Unicode object by decoding \var{size} bytes of the Unicode-Esacpe
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3133 encoded string \var{s}. Returns \NULL{} in case an exception was
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3134 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3135 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3136
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3137 \begin{cfuncdesc}{PyObject}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3138 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3139 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3140 Encodes the \ctype{Py_UNICODE} buffer of the given size using Unicode-Escape
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3141 and returns a Python string object. Returns \NULL{} in case an
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3142 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3143 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3144
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3145 \begin{cfuncdesc}{PyObject}{PyUnicode_AsUnicodeEscapeString}{PyObject unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3146 Encodes a Unicode objects using Unicode-Escape and returns the result
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3147 as Python string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3148 \NULL{} in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3149 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3150
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3151 % --- Raw-Unicode-Escape Codecs ------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3152
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3153 These are the ``Raw Unicode Esacpe'' codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3154
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3155 \begin{cfuncdesc}{PyObject}{PyUnicode_DecodeRawUnicodeEscape}{const char s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3156 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3157 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3158 Creates a Unicode object by decoding \var{size} bytes of the Raw-Unicode-Esacpe
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3159 encoded string \var{s}. Returns \NULL{} in case an exception was
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3160 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3161 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3162
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3163 \begin{cfuncdesc}{PyObject}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3164 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3165 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3166 Encodes the \ctype{Py_UNICODE} buffer of the given size using Raw-Unicode-Escape
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3167 and returns a Python string object. Returns \NULL{} in case an
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3168 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3169 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3170
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3171 \begin{cfuncdesc}{PyObject}{PyUnicode_AsRawUnicodeEscapeString}{PyObject unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3172 Encodes a Unicode objects using Raw-Unicode-Escape and returns the result
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3173 as Python string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3174 \NULL{} in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3175 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3176
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3177 % --- Latin-1 Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3178
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3179 These are the Latin-1 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3180
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3181 Latin-1 corresponds to the first 256 Unicode ordinals and only these
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3182 are accepted by the codecs during encoding.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3183
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3184 \begin{cfuncdesc}{PyObject}{PyUnicode_DecodeLatin1}{const char s,
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3185 int size,
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3186 const char *errors}
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3187 Creates a Unicode object by decoding \var{size} bytes of the Latin-1
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3188 encoded string \var{s}. Returns \NULL{} in case an exception was
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3189 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3190 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3191
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3192 \begin{cfuncdesc}{PyObject}{PyUnicode_EncodeLatin1}{const Py_UNICODE s,
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3193 int size,
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3194 const char *errors}
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3195 Encodes the \ctype{Py_UNICODE} buffer of the given size using Latin-1
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3196 and returns a Python string object. Returns \NULL{} in case an
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3197 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3198 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3199
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3200 \begin{cfuncdesc}{PyObject}{PyUnicode_AsLatin1String}{PyObject unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3201 Encodes a Unicode objects using Latin-1 and returns the result as
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3202 Python string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3203 \NULL{} in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3204 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3205
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3206 % --- ASCII Codecs -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3207
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3208 These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3209 accepted. All other codes generate errors.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3210
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3211 \begin{cfuncdesc}{PyObject}{PyUnicode_DecodeASCII}{const char s,
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3212 int size,
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3213 const char *errors}
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3214 Creates a Unicode object by decoding \var{size} bytes of the
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3215 \ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3216 was raised by the codec.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3217 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3218
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3219 \begin{cfuncdesc}{PyObject}{PyUnicode_EncodeASCII}{const Py_UNICODE s,
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3220 int size,
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3221 const char *errors}
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3222 Encodes the \ctype{Py_UNICODE} buffer of the given size using
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3223 \ASCII{} and returns a Python string object. Returns \NULL{} in case
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3224 an exception was raised by the codec.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3225 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3226
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3227 \begin{cfuncdesc}{PyObject}{PyUnicode_AsASCIIString}{PyObject unicode}
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3228 Encodes a Unicode objects using \ASCII{} and returns the result as Python
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3229 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3230 \NULL{} in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3231 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3232
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3233 % --- Character Map Codecs -----------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3234
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3235 These are the mapping codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3236
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3237 This codec is special in that it can be used to implement many
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3238 different codecs (and this is in fact what was done to obtain most of
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3239 the standard codecs included in the \module{encodings} package). The
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3240 codec uses mapping to encode and decode characters.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3241
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3242 Decoding mappings must map single string characters to single Unicode
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3243 characters, integers (which are then interpreted as Unicode ordinals)
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3244 or None (meaning "undefined mapping" and causing an error).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3245
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3246 Encoding mappings must map single Unicode characters to single string
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3247 characters, integers (which are then interpreted as Latin-1 ordinals)
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3248 or None (meaning "undefined mapping" and causing an error).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3249
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3250 The mapping objects provided must only support the __getitem__ mapping
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3251 interface.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3252
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3253 If a character lookup fails with a LookupError, the character is
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3254 copied as-is meaning that its ordinal value will be interpreted as
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3255 Unicode or Latin-1 ordinal resp. Because of this, mappings only need
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3256 to contain those mappings which map characters to different code
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3257 points.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3259 \begin{cfuncdesc}{PyObject}{PyUnicode_DecodeCharmap}{const char s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3260 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3261 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3262 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3263 Creates a Unicode object by decoding \var{size} bytes of the encoded
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3264 string \var{s} using the given \var{mapping} object. Returns \NULL{}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3265 in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3266 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3267
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3268 \begin{cfuncdesc}{PyObject}{PyUnicode_EncodeCharmap}{const Py_UNICODE s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3269 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3270 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3271 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3272 Encodes the \ctype{Py_UNICODE} buffer of the given size using the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3273 given \var{mapping} object and returns a Python string object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3274 Returns \NULL{} in case an exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3275 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3276
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3277 \begin{cfuncdesc}{PyObject}{PyUnicode_AsCharmapString}{PyObject unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3278 PyObject *mapping}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3279 Encodes a Unicode objects using the given \var{mapping} object and
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3280 returns the result as Python string object. Error handling is
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3281 ``strict''. Returns \NULL{} in case an exception was raised by the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3282 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3283 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3284
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3285 The following codec API is special in that maps Unicode to Unicode.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3286
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3287 \begin{cfuncdesc}{PyObject}{PyUnicode_TranslateCharmap}{const Py_UNICODE s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3288 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3289 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3290 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3291 Translates a \ctype{Py_UNICODE} buffer of the given length by applying
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3292 a character mapping \var{table} to it and returns the resulting
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3293 Unicode object. Returns \NULL{} when an exception was raised by the
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3294 codec.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3295
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3296 The \var{mapping} table must map Unicode ordinal integers to Unicode
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3297 ordinal integers or None (causing deletion of the character).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3298
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3299 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3300 e.g. dictionaries or sequences. Unmapped character ordinals (ones
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3301 which cause a LookupError) are left untouched and are copied as-is.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3302 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3303
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3304 % --- MBCS codecs for Windows --------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3305
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3306 These are the MBCS codec APIs. They are currently only available on
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3307 Windows and use the Win32 MBCS converters to implement the
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3308 conversions. Note that MBCS (or DBCS) is a class of encodings, not
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3309 just one. The target encoding is defined by the user settings on the
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3310 machine running the codec.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3311
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3312 \begin{cfuncdesc}{PyObject}{PyUnicode_DecodeMBCS}{const char s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3313 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3314 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3315 Creates a Unicode object by decoding \var{size} bytes of the MBCS
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3316 encoded string \var{s}. Returns \NULL{} in case an exception was
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3317 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3318 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3319
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3320 \begin{cfuncdesc}{PyObject}{PyUnicode_EncodeMBCS}{const Py_UNICODE s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3321 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3322 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3323 Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3324 and returns a Python string object. Returns \NULL{} in case an
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3325 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3326 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3327
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3328 \begin{cfuncdesc}{PyObject}{PyUnicode_AsMBCSString}{PyObject unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3329 Encodes a Unicode objects using MBCS and returns the result as Python
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3330 string object. Error handling is ``strict''. Returns \NULL{} in case
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3331 an exception was raised by the codec.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3332 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3333
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3334 % --- Methods & Slots ----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3335
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3336 \subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3337
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3338 The following APIs are capable of handling Unicode objects and strings
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3339 on input (we refer to them as strings in the descriptions) and return
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3340 Unicode objects or integers as apporpriate.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3341
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3342 They all return \NULL{} or -1 in case an exception occurrs.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3343
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3344 \begin{cfuncdesc}{PyObject}{PyUnicode_Concat}{PyObject left,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3345 PyObject *right}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3346 Concat two strings giving a new Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3347 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3348
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3349 \begin{cfuncdesc}{PyObject}{PyUnicode_Split}{PyObject s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3350 PyObject *sep,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3351 int maxsplit}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3352 Split a string giving a list of Unicode strings.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3353
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3354 If sep is NULL, splitting will be done at all whitespace
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3355 substrings. Otherwise, splits occur at the given separator.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3356
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3357 At most maxsplit splits will be done. If negative, no limit is set.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3358
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3359 Separators are not included in the resulting list.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3360 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3361
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3362 \begin{cfuncdesc}{PyObject}{PyUnicode_Splitlines}{PyObject s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3363 int maxsplit}
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3364 Split a Unicode string at line breaks, returning a list of Unicode
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3365 strings. CRLF is considered to be one line break. The Line break
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3366 characters are not included in the resulting strings.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3367 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3368
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3369 \begin{cfuncdesc}{PyObject}{PyUnicode_Translate}{PyObject str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3370 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3371 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3372 Translate a string by applying a character mapping table to it and
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3373 return the resulting Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3374
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3375 The mapping table must map Unicode ordinal integers to Unicode ordinal
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3376 integers or None (causing deletion of the character).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3377
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3378 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3379 e.g. dictionaries or sequences. Unmapped character ordinals (ones
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3380 which cause a LookupError) are left untouched and are copied as-is.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3381
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3382 \var{errors} has the usual meaning for codecs. It may be \NULL{}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3383 which indicates to use the default error handling.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3384 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3385
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3386 \begin{cfuncdesc}{PyObject}{PyUnicode_Join}{PyObject separator,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3387 PyObject *seq}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3388 Join a sequence of strings using the given separator and return
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3389 the resulting Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3390 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3391
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3392 \begin{cfuncdesc}{PyObject}{PyUnicode_Tailmatch}{PyObject str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3393 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3394 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3395 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3396 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3397 Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3398 the given tail end (\var{direction} == -1 means to do a prefix match,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3399 \var{direction} == 1 a suffix match), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3400 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3401
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3402 \begin{cfuncdesc}{PyObject}{PyUnicode_Find}{PyObject str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3403 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3404 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3405 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3406 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3407 Return the first position of \var{substr} in
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3408 \var{str}[\var{start}:\var{end}] using the given \var{direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3409 (\var{direction} == 1 means to do a forward search,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3410 \var{direction} == -1 a backward search), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3411 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3412
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3413 \begin{cfuncdesc}{PyObject}{PyUnicode_Count}{PyObject str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3414 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3415 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3416 int end}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3417 Count the number of occurrences of \var{substr} in
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3418 \var{str}[\var{start}:\var{end}]
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3419 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3420
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3421 \begin{cfuncdesc}{PyObject}{PyUnicode_Replace}{PyObject str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3422 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3423 PyObject *replstr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3424 int maxcount}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3425 Replace at most \var{maxcount} occurrences of \var{substr} in
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3426 \var{str} with \var{replstr} and return the resulting Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3427 \var{maxcount} == -1 means: replace all occurrences.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3428 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3429
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3430 \begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject left, PyObject right}
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3431 Compare two strings and return -1, 0, 1 for less than, equal,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3432 greater than resp.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3433 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3434
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3435 \begin{cfuncdesc}{PyObject}{PyUnicode_Format}{PyObject format,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3436 PyObject *args}
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3437 Returns a new string object from \var{format} and \var{args}; this is
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3438 analogous to \code{\var{format} \%\ \var{args}}. The
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3439 \var{args} argument must be a tuple.
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3440 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3441
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3442 \begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3443 PyObject *element}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3444 Checks whether \var{element} is contained in \var{container} and
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3445 returns true or false accordingly.
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3446
6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3447 \var{element} has to coerce to a one element Unicode string. \code{-1} is
12258 65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3448 returned in case of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3449 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3450
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>: Fred Drake <fdrake@acm.org> parents: 12222 diff changeset	3451
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3452 \subsection{Buffer Objects \label{bufferObjects}}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3453 \sectionauthor{Greg Stein}{gstein@lyra.org}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3454
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3455 \obindex{buffer}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3456 Python objects implemented in C can export a group of functions called
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3457 the ``buffer\index{buffer interface} interface.'' These functions can
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3458 be used by an object to expose its data in a raw, byte-oriented
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3459 format. Clients of the object can use the buffer interface to access
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3460 the object data directly, without needing to copy it first.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3461
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3462 Two examples of objects that support
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3463 the buffer interface are strings and arrays. The string object exposes
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3464 the character contents in the buffer interface's byte-oriented
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3465 form. An array can also expose its contents, but it should be noted
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3466 that array elements may be multi-byte values.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3467
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3468 An example user of the buffer interface is the file object's
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3469 \method{write()} method. Any object that can export a series of bytes
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3470 through the buffer interface can be written to a file. There are a
18785 b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	3471 number of format codes to \cfunction{PyArg_ParseTuple()} that operate
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3472 against an object's buffer interface, returning data from the target
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3473 object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3474
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3475 More information on the buffer interface is provided in the section
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3476 ``Buffer Object Structures'' (section \ref{buffer-structs}), under
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3477 the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3478
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3479 A ``buffer object'' is defined in the \file{bufferobject.h} header
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3480 (included by \file{Python.h}). These objects look very similar to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3481 string objects at the Python programming level: they support slicing,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3482 indexing, concatenation, and some other standard string
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3483 operations. However, their data can come from one of two sources: from
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3484 a block of memory, or from another object which exports the buffer
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3485 interface.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3486
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3487 Buffer objects are useful as a way to expose the data from another
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3488 object's buffer interface to the Python programmer. They can also be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3489 used as a zero-copy slicing mechanism. Using their ability to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3490 reference a block of memory, it is possible to expose any data to the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3491 Python programmer quite easily. The memory could be a large, constant
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3492 array in a C extension, it could be a raw block of memory for
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3493 manipulation before passing to an operating system library, or it
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3494 could be used to pass around structured data in its native, in-memory
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3495 format.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3496
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3497 \begin{ctypedesc}{PyBufferObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3498 This subtype of \ctype{PyObject} represents a buffer object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3499 \end{ctypedesc}
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3500
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3501 \begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3502 The instance of \ctype{PyTypeObject} which represents the Python
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3503 buffer type; it is the same object as \code{types.BufferType} in the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3504 Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3505 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3506
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3507 \begin{cvardesc}{int}{Py_END_OF_BUFFER}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3508 This constant may be passed as the \var{size} parameter to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3509 \cfunction{PyBuffer_FromObject()} or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3510 \cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the new
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3511 \ctype{PyBufferObject} should refer to \var{base} object from the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3512 specified \var{offset} to the end of its exported buffer. Using this
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3513 enables the caller to avoid querying the \var{base} object for its
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3514 length.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3515 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3516
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3517 \begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3518 Return true if the argument has type \cdata{PyBuffer_Type}.
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3519 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3520
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3521 \begin{cfuncdesc}{PyObject}{PyBuffer_FromObject}{PyObject base,
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3522 int offset, int size}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3523 Return a new read-only buffer object. This raises
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3524 \exception{TypeError} if \var{base} doesn't support the read-only
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3525 buffer protocol or doesn't provide exactly one buffer segment, or it
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3526 raises \exception{ValueError} if \var{offset} is less than zero. The
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3527 buffer will hold a reference to the \var{base} object, and the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3528 buffer's contents will refer to the \var{base} object's buffer
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3529 interface, starting as position \var{offset} and extending for
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3530 \var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3531 the new buffer's contents extend to the length of the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3532 \var{base} object's exported buffer data.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3533 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3534
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3535 \begin{cfuncdesc}{PyObject}{PyBuffer_FromReadWriteObject}{PyObject base,
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3536 int offset,
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3537 int size}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3538 Return a new writable buffer object. Parameters and exceptions are
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3539 similar to those for \cfunction{PyBuffer_FromObject()}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3540 If the \var{base} object does not export the writeable buffer
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3541 protocol, then \exception{TypeError} is raised.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3542 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3543
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3544 \begin{cfuncdesc}{PyObject}{PyBuffer_FromMemory}{void ptr, int size}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3545 Return a new read-only buffer object that reads from a specified
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3546 location in memory, with a specified size.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3547 The caller is responsible for ensuring that the memory buffer, passed
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3548 in as \var{ptr}, is not deallocated while the returned buffer object
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3549 exists. Raises \exception{ValueError} if \var{size} is less than
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3550 zero. Note that \constant{Py_END_OF_BUFFER} may \emph{not} be passed
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3551 for the \var{size} parameter; \exception{ValueError} will be raised in
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3552 that case.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3553 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3554
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3555 \begin{cfuncdesc}{PyObject}{PyBuffer_FromReadWriteMemory}{void ptr, int size}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3556 Similar to \cfunction{PyBuffer_FromMemory()}, but the returned buffer
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3557 is writable.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3558 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3559
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3560 \begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3561 Returns a new writable buffer object that maintains its own memory
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3562 buffer of \var{size} bytes. \exception{ValueError} is returned if
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3563 \var{size} is not zero or positive.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3564 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	3565
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3566
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	3567 \subsection{Tuple Objects \label{tupleObjects}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3568
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3569 \obindex{tuple}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3570 \begin{ctypedesc}{PyTupleObject}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3571 This subtype of \ctype{PyObject} represents a Python tuple object.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3572 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3573
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3574 \begin{cvardesc}{PyTypeObject}{PyTuple_Type}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3575 This instance of \ctype{PyTypeObject} represents the Python tuple
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3576 type; it is the same object as \code{types.TupleType} in the Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3577 layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3578 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3579
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3580 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3581 Return true if the argument is a tuple object.
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3582 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3583
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3584 \begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3585 Return a new tuple object of size \var{len}, or \NULL{} on failure.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3586 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3587
16577 068cb8494b7b PyTuple_() functions take PyObject parameters, not PyTupleObject* values. Fred Drake <fdrake@acm.org> parents: 16439 diff changeset	3588 \begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3589 Takes a pointer to a tuple object, and returns the size
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3590 of that tuple.
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3591 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3592
16577 068cb8494b7b PyTuple_() functions take PyObject parameters, not PyTupleObject* values. Fred Drake <fdrake@acm.org> parents: 16439 diff changeset	3593 \begin{cfuncdesc}{PyObject}{PyTuple_GetItem}{PyObject p, int pos}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3594 Returns the object at position \var{pos} in the tuple pointed
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3595 to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3596 sets an \exception{IndexError} exception.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3597 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3598
16577 068cb8494b7b PyTuple_() functions take PyObject parameters, not PyTupleObject* values. Fred Drake <fdrake@acm.org> parents: 16439 diff changeset	3599 \begin{cfuncdesc}{PyObject}{PyTuple_GET_ITEM}{PyObject p, int pos}
17981 a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3600 Like \cfunction{PyTuple_GetItem()}, but does no checking of its
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3601 arguments.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3602 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3603
16577 068cb8494b7b PyTuple_() functions take PyObject parameters, not PyTupleObject* values. Fred Drake <fdrake@acm.org> parents: 16439 diff changeset	3604 \begin{cfuncdesc}{PyObject}{PyTuple_GetSlice}{PyObject p,
068cb8494b7b PyTuple_() functions take PyObject parameters, not PyTupleObject* values. Fred Drake <fdrake@acm.org> parents: 16439 diff changeset	3605 int low, int high}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3606 Takes a slice of the tuple pointed to by \var{p} from
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3607 \var{low} to \var{high} and returns it as a new tuple.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3608 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3609
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3610 \begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3611 int pos, PyObject *o}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3612 Inserts a reference to object \var{o} at position \var{pos} of
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3613 the tuple pointed to by \var{p}. It returns \code{0} on success.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3614 \strong{Note:} This function ``steals'' a reference to \var{o}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3615 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3616
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3617 \begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3618 int pos, PyObject *o}
17981 a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3619 Like \cfunction{PyTuple_SetItem()}, but does no error checking, and
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3620 should \emph{only} be used to fill in brand new tuples.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3621 \strong{Note:} This function ``steals'' a reference to \var{o}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3622 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3623
17981 a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3624 \begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3625 Can be used to resize a tuple. \var{newsize} will be the new length
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3626 of the tuple. Because tuples are \emph{supposed} to be immutable,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3627 this should only be used if there is only one reference to the object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3628 Do \emph{not} use this if the tuple may already be known to some other
17981 a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3629 part of the code. The tuple will always grow or shrink at the end.
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3630 Think of this as destroying the old tuple and creating a new one, only
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3631 more efficiently. Returns \code{0} on success. Client code should
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3632 never assume that the resulting value of \code{*\var{p}} will be the
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3633 same as before calling this function. If the object referenced by
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3634 \code{\var{p}} is replaced, the original \code{\var{p}} is
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3635 destroyed. On failure, returns \code{-1} and sets \code{*\var{p}} to
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3636 \NULL, and raises \exception{MemoryError} or \exception{SystemError}.
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually Fred Drake <fdrake@acm.org> parents: 17877 diff changeset	3637 \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3638 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3639
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3640
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	3641 \subsection{List Objects \label{listObjects}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3642
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3643 \obindex{list}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3644 \begin{ctypedesc}{PyListObject}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3645 This subtype of \ctype{PyObject} represents a Python list object.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3646 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3647
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3648 \begin{cvardesc}{PyTypeObject}{PyList_Type}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3649 This instance of \ctype{PyTypeObject} represents the Python list
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3650 type. This is the same object as \code{types.ListType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3651 \withsubitem{(in module types)}{\ttindex{ListType}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3652 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3653
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3654 \begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3655 Returns true if its argument is a \ctype{PyListObject}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3656 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3657
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3658 \begin{cfuncdesc}{PyObject*}{PyList_New}{int len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3659 Returns a new list of length \var{len} on success, or \NULL{} on
8057 5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes. Guido van Rossum <guido@python.org> parents: 8029 diff changeset	3660 failure.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3661 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3662
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3663 \begin{cfuncdesc}{int}{PyList_Size}{PyObject *list}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3664 Returns the length of the list object in \var{list}; this is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3665 equivalent to \samp{len(\var{list})} on a list object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3666 \bifuncindex{len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3667 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3668
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3669 \begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
15087 a13a2acbe214 Fix a couple of places where the descriptions of _GET_SIZE() macros said Fred Drake <fdrake@acm.org>* parents: 15038 diff changeset	3670 Macro form of \cfunction{PyList_Size()} without error checking.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3671 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3672
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3673 \begin{cfuncdesc}{PyObject}{PyList_GetItem}{PyObject list, int index}
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3674 Returns the object at position \var{pos} in the list pointed
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3675 to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3676 sets an \exception{IndexError} exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3677 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3678
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3679 \begin{cfuncdesc}{PyObject}{PyList_GET_ITEM}{PyObject list, int i}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3680 Macro form of \cfunction{PyList_GetItem()} without error checking.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3681 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3682
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3683 \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3684 PyObject *item}
8057 5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes. Guido van Rossum <guido@python.org> parents: 8029 diff changeset	3685 Sets the item at index \var{index} in list to \var{item}.
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3686 Returns \code{0} on success or \code{-1} on failure.
18020 e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM(). Fred Drake <fdrake@acm.org> parents: 18000 diff changeset	3687 \strong{Note:} This function ``steals'' a reference to \var{item} and
e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM(). Fred Drake <fdrake@acm.org> parents: 18000 diff changeset	3688 discards a reference to an item already in the list at the affected
e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM(). Fred Drake <fdrake@acm.org> parents: 18000 diff changeset	3689 position.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3690 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3691
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3692 \begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i,
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3693 PyObject *o}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3694 Macro form of \cfunction{PyList_SetItem()} without error checking.
18020 e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM(). Fred Drake <fdrake@acm.org> parents: 18000 diff changeset	3695 \strong{Note:} This function ``steals'' a reference to \var{item},
e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM(). Fred Drake <fdrake@acm.org> parents: 18000 diff changeset	3696 and, unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3697 reference to any item that it being replaced; any reference in
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3698 \var{list} at position \var{i} will be leaked. This is normally only
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3699 used to fill in new lists where there is no previous content.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3700 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3701
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3702 \begin{cfuncdesc}{int}{PyList_Insert}{PyObject *list, int index,
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3703 PyObject *item}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3704 Inserts the item \var{item} into list \var{list} in front of index
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3705 \var{index}. Returns \code{0} if successful; returns \code{-1} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3706 raises an exception if unsuccessful. Analogous to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3707 \code{\var{list}.insert(\var{index}, \var{item})}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3708 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3709
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3710 \begin{cfuncdesc}{int}{PyList_Append}{PyObject list, PyObject item}
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3711 Appends the object \var{item} at the end of list \var{list}. Returns
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3712 \code{0} if successful; returns \code{-1} and sets an exception if
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3713 unsuccessful. Analogous to \code{\var{list}.append(\var{item})}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3714 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3715
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3716 \begin{cfuncdesc}{PyObject}{PyList_GetSlice}{PyObject list,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3717 int low, int high}
8057 5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes. Guido van Rossum <guido@python.org> parents: 8029 diff changeset	3718 Returns a list of the objects in \var{list} containing the objects
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3719 \emph{between} \var{low} and \var{high}. Returns NULL and sets an
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3720 exception if unsuccessful.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3721 Analogous to \code{\var{list}[\var{low}:\var{high}]}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3722 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3723
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3724 \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3725 int low, int high,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3726 PyObject *itemlist}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3727 Sets the slice of \var{list} between \var{low} and \var{high} to the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3728 contents of \var{itemlist}. Analogous to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3729 \code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}. Returns
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3730 \code{0} on success, \code{-1} on failure.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3731 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3732
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3733 \begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3734 Sorts the items of \var{list} in place. Returns \code{0} on success,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3735 \code{-1} on failure. This is equivalent to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3736 \samp{\var{list}.sort()}.
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3737 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3738
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3739 \begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3740 Reverses the items of \var{list} in place. Returns \code{0} on
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3741 success, \code{-1} on failure. This is the equivalent of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3742 \samp{\var{list}.reverse()}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3743 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3744
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3745 \begin{cfuncdesc}{PyObject}{PyList_AsTuple}{PyObject list}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3746 Returns a new tuple object containing the contents of \var{list};
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3747 equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3748 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3749
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3750
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	3751 \section{Mapping Objects \label{mapObjects}}
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	3752
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3753 \obindex{mapping}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3754
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3755
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	3756 \subsection{Dictionary Objects \label{dictObjects}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3757
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3758 \obindex{dictionary}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3759 \begin{ctypedesc}{PyDictObject}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3760 This subtype of \ctype{PyObject} represents a Python dictionary object.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3761 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3762
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3763 \begin{cvardesc}{PyTypeObject}{PyDict_Type}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3764 This instance of \ctype{PyTypeObject} represents the Python dictionary
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3765 type. This is exposed to Python programs as \code{types.DictType} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3766 \code{types.DictionaryType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3767 \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3768 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3769
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3770 \begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3771 Returns true if its argument is a \ctype{PyDictObject}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3772 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3773
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3774 \begin{cfuncdesc}{PyObject*}{PyDict_New}{}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3775 Returns a new empty dictionary, or \NULL{} on failure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3776 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3777
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3778 \begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3779 Empties an existing dictionary of all key-value pairs.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3780 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3781
12126 e6214ad2a60c Add PyDict_Copy() function to C API for dicts. It returns a new Jeremy Hylton <jeremy@alum.mit.edu> parents: 11453 diff changeset	3782 \begin{cfuncdesc}{PyObject}{PyDict_Copy}{PyObject p}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3783 Returns a new dictionary that contains the same key-value pairs as p.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3784 Empties an existing dictionary of all key-value pairs.
19156 776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3785 \versionadded{1.6}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3786 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3787
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3788 \begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject p, PyObject key,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3789 PyObject *val}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3790 Inserts \var{value} into the dictionary \var{p} with a key of \var{key}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3791 \var{key} must be hashable; if it isn't, \exception{TypeError} will be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3792 raised.
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3793 Returns \code{0} on success or \code{-1} on failure.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3794 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3795
17057 797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3796 \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3797 char *key,
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3798 PyObject *val}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3799 Inserts \var{value} into the dictionary \var{p} using \var{key}
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	3800 as a key. \var{key} should be a \ctype{char*}. The key object is
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3801 created using \code{PyString_FromString(\var{key})}.
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3802 Returns \code{0} on success or \code{-1} on failure.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3803 \ttindex{PyString_FromString()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3804 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3805
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3806 \begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject p, PyObject key}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3807 Removes the entry in dictionary \var{p} with key \var{key}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3808 \var{key} must be hashable; if it isn't, \exception{TypeError} is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3809 raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3810 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3811
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3812 \begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject p, char key}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3813 Removes the entry in dictionary \var{p} which has a key
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3814 specified by the string \var{key}.
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	3815 Returns \code{0} on success or \code{-1} on failure.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3816 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3817
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3818 \begin{cfuncdesc}{PyObject}{PyDict_GetItem}{PyObject p, PyObject *key}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	3819 Returns the object from dictionary \var{p} which has a key
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3820 \var{key}. Returns \NULL{} if the key \var{key} is not present, but
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3821 \emph{without} setting an exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3822 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3823
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3824 \begin{cfuncdesc}{PyObject}{PyDict_GetItemString}{PyObject p, char *key}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3825 This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3826 specified as a \ctype{char}, rather than a \ctype{PyObject}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3827 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3828
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3829 \begin{cfuncdesc}{PyObject}{PyDict_Items}{PyObject p}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3830 Returns a \ctype{PyListObject} containing all the items
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3831 from the dictionary, as in the dictinoary method \method{items()} (see
11451 38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	3832 the \citetitle[../lib/lib.html]{Python Library Reference}).
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3833 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3834
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3835 \begin{cfuncdesc}{PyObject}{PyDict_Keys}{PyObject p}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3836 Returns a \ctype{PyListObject} containing all the keys
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3837 from the dictionary, as in the dictionary method \method{keys()} (see the
11451 38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	3838 \citetitle[../lib/lib.html]{Python Library Reference}).
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3839 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3840
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3841 \begin{cfuncdesc}{PyObject}{PyDict_Values}{PyObject p}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3842 Returns a \ctype{PyListObject} containing all the values
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	3843 from the dictionary \var{p}, as in the dictionary method
11451 38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	3844 \method{values()} (see the \citetitle[../lib/lib.html]{Python Library
38c7444f633a Use \citetitle and \programopt as appropriate. Fred Drake <fdrake@acm.org> parents: 11222 diff changeset	3845 Reference}).
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3846 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3847
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3848 \begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3849 Returns the number of items in the dictionary. This is equivalent to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3850 \samp{len(\var{p})} on a dictionary.\bifuncindex{len}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3851 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3852
17057 797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3853 \begin{cfuncdesc}{int}{PyDict_Next}{PyObject p, int ppos,
13920 d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C. Fred Drake <fdrake@acm.org> parents: 13592 diff changeset	3854 PyObject pkey, PyObject pvalue}
17057 797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3855 Iterate over all key-value pairs in the dictionary \var{p}. The
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3856 \ctype{int} referred to by \var{ppos} must be initialized to \code{0}
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3857 prior to the first call to this function to start the iteration; the
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3858 function returns true for each pair in the dictionary, and false once
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3859 all pairs have been reported. The parameters \var{pkey} and
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3860 \var{pvalue} should either point to \ctype{PyObject*} variables that
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3861 will be filled in with each key and value, respectively, or may be
17504 8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3862 \NULL.
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3863
17057 797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3864 For example:
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3865
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3866 \begin{verbatim}
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3867 PyObject key, value;
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3868 int pos = 0;
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3869
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3870 while (PyDict_Next(self->dict, &pos, &key, &value)) {
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3871 /* do something interesting with the values... */
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3872 ...
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3873 }
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is Fred Drake <fdrake@acm.org> parents: 16872 diff changeset	3874 \end{verbatim}
17504 8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3875
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3876 The dictionary \var{p} should not be mutated during iteration. It is
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3877 safe (since Python 2.1) to modify the values of the keys as you
19156 776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3878 iterate over the dictionary, but only so long as the set of keys does
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3879 not change. For example:
17504 8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3880
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3881 \begin{verbatim}
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3882 PyObject key, value;
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3883 int pos = 0;
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3884
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3885 while (PyDict_Next(self->dict, &pos, &key, &value)) {
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3886 int i = PyInt_AS_LONG(value) + 1;
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3887 PyObject *o = PyInt_FromLong(i);
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3888 if (o == NULL)
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3889 return -1;
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3890 if (PyDict_SetItem(self->dict, key, o) < 0) {
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3891 Py_DECREF(o);
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3892 return -1;
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3893 }
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3894 Py_DECREF(o);
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3895 }
8e1415ef9b28 Michael Hudson: Fred Drake <fdrake@acm.org> parents: 17480 diff changeset	3896 \end{verbatim}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3897 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3898
19156 776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3899 \begin{cfuncdesc}{int}{PyDict_Merge}{PyObject a, PyObject b, int override}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3900 Iterate over dictionary \var{b} adding key-value pairs to dictionary
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3901 \var{a}. If \var{override} is true, existing pairs in \var{a} will be
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3902 replaced if a matching key is found in \var{b}, otherwise pairs will
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3903 only be added if there is not a matching key in \var{a}. Returns
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3904 \code{0} on success or \code{-1} if an exception was raised.
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3905 \versionadded{2.2}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3906 \end{cfuncdesc}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3907
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3908 \begin{cfuncdesc}{int}{PyDict_Update}{PyObject a, PyObject b}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3909 This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C, or
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3910 \code{\var{a}.update(\var{b})} in Python. Returns \code{0} on success
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3911 or \code{-1} if an exception was raised.
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3912 \versionadded{2.2}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3913 \end{cfuncdesc}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge(). Fred Drake <fdrake@acm.org> parents: 19126 diff changeset	3914
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3915
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	3916 \section{Other Objects \label{otherObjects}}
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	3917
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	3918 \subsection{File Objects \label{fileObjects}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3919
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3920 \obindex{file}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3921 Python's built-in file objects are implemented entirely on the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3922 \ctype{FILE*} support from the C standard library. This is an
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3923 implementation detail and may change in future releases of Python.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3924
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3925 \begin{ctypedesc}{PyFileObject}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3926 This subtype of \ctype{PyObject} represents a Python file object.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3927 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3928
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3929 \begin{cvardesc}{PyTypeObject}{PyFile_Type}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3930 This instance of \ctype{PyTypeObject} represents the Python file
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3931 type. This is exposed to Python programs as \code{types.FileType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3932 \withsubitem{(in module types)}{\ttindex{FileType}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3933 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3934
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3935 \begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	3936 Returns true if its argument is a \ctype{PyFileObject}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3937 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3938
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3939 \begin{cfuncdesc}{PyObject}{PyFile_FromString}{char filename, char *mode}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3940 On success, returns a new file object that is opened on the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3941 file given by \var{filename}, with a file mode given by \var{mode},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3942 where \var{mode} has the same semantics as the standard C routine
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3943 \cfunction{fopen()}\ttindex{fopen()}. On failure, returns \NULL.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3944 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3945
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3946 \begin{cfuncdesc}{PyObject}{PyFile_FromFile}{FILE fp,
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3947 char name, char mode,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3948 int (close)(FILE)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3949 Creates a new \ctype{PyFileObject} from the already-open standard C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3950 file pointer, \var{fp}. The function \var{close} will be called when
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3951 the file should be closed. Returns \NULL{} on failure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3952 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3953
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3954 \begin{cfuncdesc}{FILE}{PyFile_AsFile}{PyFileObject p}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3955 Returns the file object associated with \var{p} as a \ctype{FILE*}.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3956 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3957
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3958 \begin{cfuncdesc}{PyObject}{PyFile_GetLine}{PyObject p, int n}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3959 Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3960 function reads one line from the object \var{p}. \var{p} may be a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3961 file object or any object with a \method{readline()} method. If
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3962 \var{n} is \code{0}, exactly one line is read, regardless of the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3963 length of the line. If \var{n} is greater than \code{0}, no more than
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3964 \var{n} bytes will be read from the file; a partial line can be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3965 returned. In both cases, an empty string is returned if the end of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3966 the file is reached immediately. If \var{n} is less than \code{0},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3967 however, one line is read regardless of length, but
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3968 \exception{EOFError} is raised if the end of the file is reached
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3969 immediately.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3970 \withsubitem{(built-in exception)}{\ttindex{EOFError}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3971 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3972
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3973 \begin{cfuncdesc}{PyObject}{PyFile_Name}{PyObject p}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3974 Returns the name of the file specified by \var{p} as a string object.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3975 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3976
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3977 \begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3978 Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3979 only. This should only be called immediately after file object
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3980 creation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3981 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3982
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3983 \begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3984 This function exists for internal use by the interpreter.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3985 Sets the \member{softspace} attribute of \var{p} to \var{newflag} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3986 \withsubitem{(file attribute)}{\ttindex{softspace}}returns the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3987 previous value. \var{p} does not have to be a file object
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3988 for this function to work properly; any object is supported (thought
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3989 its only interesting if the \member{softspace} attribute can be set).
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3990 This function clears any errors, and will return \code{0} as the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3991 previous value if the attribute either does not exist or if there were
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3992 errors in retrieving it. There is no way to detect errors from this
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3993 function, but doing so should not be needed.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3994 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	3995
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3996 \begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject obj, PyFileObject p,
7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	3997 int flags}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3998 Writes object \var{obj} to file object \var{p}. The only supported
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	3999 flag for \var{flags} is \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW};
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4000 if given, the \function{str()} of the object is written instead of the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4001 \function{repr()}. Returns \code{0} on success or \code{-1} on
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4002 failure; the appropriate exception will be set.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	4003 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	4004
19126 67be3a68fde4 Remove the bogus flags parameter from the PyFile_WriteString() signature; Fred Drake <fdrake@acm.org> parents: 19076 diff changeset	4005 \begin{cfuncdesc}{int}{PyFile_WriteString}{char s, PyFileObject p}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4006 Writes string \var{s} to file object \var{p}. Returns \code{0} on
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4007 success or \code{-1} on failure; the appropriate exception will be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4008 set.
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	4009 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	4010
682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	4011
16318 17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4012 \subsection{Instance Objects \label{instanceObjects}}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4013
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4014 \obindex{instance}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4015 There are very few functions specific to instance objects.
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4016
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4017 \begin{cvardesc}{PyTypeObject}{PyInstance_Type}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4018 Type object for class instances.
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4019 \end{cvardesc}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4020
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4021 \begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4022 Returns true if \var{obj} is an instance.
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4023 \end{cfuncdesc}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4024
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4025 \begin{cfuncdesc}{PyObject}{PyInstance_New}{PyObject class,
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4026 PyObject *arg,
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4027 PyObject *kw}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4028 Create a new instance of a specific class. The parameters \var{arg}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4029 and \var{kw} are used as the positional and keyword parameters to
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4030 the object's constructor.
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4031 \end{cfuncdesc}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4032
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4033 \begin{cfuncdesc}{PyObject}{PyInstance_NewRaw}{PyObject class,
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4034 PyObject *dict}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4035 Create a new instance of a specific class without calling it's
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4036 constructor. \var{class} is the class of new object. The
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4037 \var{dict} parameter will be used as the object's \member{__dict__};
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4038 if \NULL, a new dictionary will be created for the instance.
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4039 \end{cfuncdesc}
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4040
17cac70cae76 Document the PyInstance_() functions and data. Fred Drake <fdrake@acm.org>* parents: 16053 diff changeset	4041
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4042 \subsection{Module Objects \label{moduleObjects}}
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4043
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4044 \obindex{module}
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4045 There are only a few functions special to module objects.
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4046
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4047 \begin{cvardesc}{PyTypeObject}{PyModule_Type}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4048 This instance of \ctype{PyTypeObject} represents the Python module
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4049 type. This is exposed to Python programs as \code{types.ModuleType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4050 \withsubitem{(in module types)}{\ttindex{ModuleType}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4051 \end{cvardesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4052
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4053 \begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4054 Returns true if its argument is a module object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4055 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4056
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4057 \begin{cfuncdesc}{PyObject}{PyModule_New}{char name}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4058 Return a new module object with the \member{__name__} attribute set to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4059 \var{name}. Only the module's \member{__doc__} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4060 \member{__name__} attributes are filled in; the caller is responsible
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4061 for providing a \member{__file__} attribute.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4062 \withsubitem{(module attribute)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4063 \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4064 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4065
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4066 \begin{cfuncdesc}{PyObject}{PyModule_GetDict}{PyObject module}
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4067 Return the dictionary object that implements \var{module}'s namespace;
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4068 this object is the same as the \member{__dict__} attribute of the
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4069 module object. This function never fails.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4070 \withsubitem{(module attribute)}{\ttindex{__dict__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4071 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4072
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4073 \begin{cfuncdesc}{char}{PyModule_GetName}{PyObject module}
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4074 Return \var{module}'s \member{__name__} value. If the module does not
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4075 provide one, or if it is not a string, \exception{SystemError} is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4076 raised and \NULL{} is returned.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4077 \withsubitem{(module attribute)}{\ttindex{__name__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4078 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4079 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4080
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4081 \begin{cfuncdesc}{char}{PyModule_GetFilename}{PyObject module}
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4082 Return the name of the file from which \var{module} was loaded using
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4083 \var{module}'s \member{__file__} attribute. If this is not defined,
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4084 or if it is not a string, raise \exception{SystemError} and return
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4085 \NULL.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4086 \withsubitem{(module attribute)}{\ttindex{__file__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4087 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4088 \end{cfuncdesc}
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4089
14782 3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4090 \begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module,
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4091 char name, PyObject value}
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4092 Add an object to \var{module} as \var{name}. This is a convenience
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4093 function which can be used from the module's initialization function.
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4094 This steals a reference to \var{value}. Returns \code{-1} on error,
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4095 \code{0} on success.
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4096 \versionadded{2.0}
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4097 \end{cfuncdesc}
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4098
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4099 \begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4100 char *name, int value}
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4101 Add an integer constant to \var{module} as \var{name}. This convenience
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4102 function can be used from the module's initialization function.
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4103 Returns \code{-1} on error, \code{0} on success.
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4104 \versionadded{2.0}
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4105 \end{cfuncdesc}
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4106
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4107 \begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4108 char name, char value}
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4109 Add a string constant to \var{module} as \var{name}. This convenience
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4110 function can be used from the module's initialization function. The
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4111 string \var{value} must be null-terminated. Returns \code{-1} on
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4112 error, \code{0} on success.
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4113 \versionadded{2.0}
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4114 \end{cfuncdesc}
3c01f921c453 Added documentation for the new PyModule_() convenience functions. Fred Drake <fdrake@acm.org>* parents: 14769 diff changeset	4115
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4116
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4117 \subsection{CObjects \label{cObjects}}
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	4118
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4119 \obindex{CObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4120 Refer to \emph{Extending and Embedding the Python Interpreter},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4121 section 1.12 (``Providing a C API for an Extension Module''), for more
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4122 information on using these objects.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4123
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4124
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4125 \begin{ctypedesc}{PyCObject}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4126 This subtype of \ctype{PyObject} represents an opaque value, useful for
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4127 C extension modules who need to pass an opaque value (as a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4128 \ctype{void*} pointer) through Python code to other C code. It is
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4129 often used to make a C function pointer defined in one module
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4130 available to other modules, so the regular import mechanism can be
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4131 used to access C APIs defined in dynamically loaded modules.
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4132 \end{ctypedesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4133
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4134 \begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4135 Returns true if its argument is a \ctype{PyCObject}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4136 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4137
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4138 \begin{cfuncdesc}{PyObject}{PyCObject_FromVoidPtr}{void cobj,
15953 8349b4dfc51a Undoing the whitespace patches which sneaked into the earlier patch. Marc-André Lemburg <mal@egenix.com> parents: 15952 diff changeset	4139 void (destr)(void )}
12947 6b2ecd172203 Markup consistency nits. Fred Drake <fdrake@acm.org> parents: 12932 diff changeset	4140 Creates a \ctype{PyCObject} from the \code{void *}\var{cobj}. The
10851 fcb25335d6ae PyCObject_FromVoidPtr(): Clarify that the destr function will only be Fred Drake <fdrake@acm.org> parents: 10786 diff changeset	4141 \var{destr} function will be called when the object is reclaimed, unless
fcb25335d6ae PyCObject_FromVoidPtr(): Clarify that the destr function will only be Fred Drake <fdrake@acm.org> parents: 10786 diff changeset	4142 it is \NULL.
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4143 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4144
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4145 \begin{cfuncdesc}{PyObject}{PyCObject_FromVoidPtrAndDesc}{void cobj,
15953 8349b4dfc51a Undoing the whitespace patches which sneaked into the earlier patch. Marc-André Lemburg <mal@egenix.com> parents: 15952 diff changeset	4146 void* desc, void (destr)(void , void *) }
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4147 Creates a \ctype{PyCObject} from the \ctype{void *}\var{cobj}. The
068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4148 \var{destr} function will be called when the object is reclaimed. The
068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4149 \var{desc} argument can be used to pass extra callback data for the
068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4150 destructor function.
8109 2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4151 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag. Guido van Rossum <guido@python.org> parents: 8057 diff changeset	4152
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4153 \begin{cfuncdesc}{void}{PyCObject_AsVoidPtr}{PyObject self}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4154 Returns the object \ctype{void *} that the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4155 \ctype{PyCObject} \var{self} was created with.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4156 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4157
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4158 \begin{cfuncdesc}{void}{PyCObject_GetDesc}{PyObject self}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4159 Returns the description \ctype{void *} that the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4160 \ctype{PyCObject} \var{self} was created with.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4161 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4162
7269 682d3e5b267f Reorganized a bit. No changed content. Fred Drake <fdrake@acm.org> parents: 7268 diff changeset	4163
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4164 \chapter{Initialization, Finalization, and Threads
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4165 \label{initialization}}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4166
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4167 \begin{cfuncdesc}{void}{Py_Initialize}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4168 Initialize the Python interpreter. In an application embedding
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4169 Python, this should be called before using any other Python/C API
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4170 functions; with the exception of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4171 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4172 \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4173 \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4174 and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4175 This initializes the table of loaded modules (\code{sys.modules}), and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4176 \withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}creates the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4177 fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
7310 6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4178 \module{__main__}\refbimodindex{__main__} and
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4179 \module{sys}\refbimodindex{sys}. It also initializes the module
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4180 search\indexiii{module}{search}{path} path (\code{sys.path}).
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4181 It does not set \code{sys.argv}; use
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4182 \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that. This
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4183 is a no-op when called for a second time (without calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4184 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first). There is no
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4185 return value; it is a fatal error if the initialization fails.
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	4186 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	4187
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	4188 \begin{cfuncdesc}{int}{Py_IsInitialized}{}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	4189 Return true (nonzero) when the Python interpreter has been
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4190 initialized, false (zero) if not. After \cfunction{Py_Finalize()} is
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4191 called, this returns false until \cfunction{Py_Initialize()} is called
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	4192 again.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4193 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4194
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4195 \begin{cfuncdesc}{void}{Py_Finalize}{}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4196 Undo all initializations made by \cfunction{Py_Initialize()} and
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4197 subsequent use of Python/C API functions, and destroy all
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4198 sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4199 created and not yet destroyed since the last call to
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4200 \cfunction{Py_Initialize()}. Ideally, this frees all memory allocated
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4201 by the Python interpreter. This is a no-op when called for a second
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4202 time (without calling \cfunction{Py_Initialize()} again first). There
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4203 is no return value; errors during finalization are ignored.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4204
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4205 This function is provided for a number of reasons. An embedding
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4206 application might want to restart Python without having to restart the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4207 application itself. An application that has loaded the Python
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4208 interpreter from a dynamically loadable library (or DLL) might want to
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4209 free all memory allocated by Python before unloading the DLL. During a
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4210 hunt for memory leaks in an application a developer might want to free
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4211 all memory allocated by Python before exiting from the application.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4212
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4213 \strong{Bugs and caveats:} The destruction of modules and objects in
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4214 modules is done in random order; this may cause destructors
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4215 (\method{__del__()} methods) to fail when they depend on other objects
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4216 (even functions) or modules. Dynamically loaded extension modules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4217 loaded by Python are not unloaded. Small amounts of memory allocated
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4218 by the Python interpreter may not be freed (if you find a leak, please
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4219 report it). Memory tied up in circular references between objects is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4220 not freed. Some memory allocated by extension modules may not be
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4221 freed. Some extension may not work properly if their initialization
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4222 routine is called more than once; this can happen if an applcation
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4223 calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4224 than once.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4225 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4226
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4227 \begin{cfuncdesc}{PyThreadState*}{Py_NewInterpreter}{}
7310 6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4228 Create a new sub-interpreter. This is an (almost) totally separate
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4229 environment for the execution of Python code. In particular, the new
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4230 interpreter has separate, independent versions of all imported
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4231 modules, including the fundamental modules
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4232 \module{__builtin__}\refbimodindex{__builtin__},
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4233 \module{__main__}\refbimodindex{__main__} and
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4234 \module{sys}\refbimodindex{sys}. The table of loaded modules
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4235 (\code{sys.modules}) and the module search path (\code{sys.path}) are
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4236 also separate. The new environment has no \code{sys.argv} variable.
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4237 It has new standard I/O stream file objects \code{sys.stdin},
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4238 \code{sys.stdout} and \code{sys.stderr} (however these refer to the
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4239 same underlying \ctype{FILE} structures in the C library).
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4240 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4241 \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4242
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4243 The return value points to the first thread state created in the new
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4244 sub-interpreter. This thread state is made the current thread state.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4245 Note that no actual thread is created; see the discussion of thread
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4246 states below. If creation of the new interpreter is unsuccessful,
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4247 \NULL{} is returned; no exception is set since the exception state
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4248 is stored in the current thread state and there may not be a current
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4249 thread state. (Like all other Python/C API functions, the global
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4250 interpreter lock must be held before calling this function and is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4251 still held when it returns; however, unlike most other Python/C API
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4252 functions, there needn't be a current thread state on entry.)
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4253
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4254 Extension modules are shared between (sub-)interpreters as follows:
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4255 the first time a particular extension is imported, it is initialized
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4256 normally, and a (shallow) copy of its module's dictionary is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4257 squirreled away. When the same extension is imported by another
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4258 (sub-)interpreter, a new module is initialized and filled with the
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4259 contents of this copy; the extension's \code{init} function is not
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4260 called. Note that this is different from what happens when an
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4261 extension is imported after the interpreter has been completely
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4262 re-initialized by calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4263 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4264 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4265 the extension's \code{init\var{module}} function \emph{is} called
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4266 again.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4267
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4268 \strong{Bugs and caveats:} Because sub-interpreters (and the main
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4269 interpreter) are part of the same process, the insulation between them
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4270 isn't perfect --- for example, using low-level file operations like
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4271 \withsubitem{(in module os)}{\ttindex{close()}}
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4272 \function{os.close()} they can (accidentally or maliciously) affect each
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4273 other's open files. Because of the way extensions are shared between
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4274 (sub-)interpreters, some extensions may not work properly; this is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4275 especially likely when the extension makes use of (static) global
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4276 variables, or when the extension manipulates its module's dictionary
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4277 after its initialization. It is possible to insert objects created in
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4278 one sub-interpreter into a namespace of another sub-interpreter; this
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4279 should be done with great care to avoid sharing user-defined
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4280 functions, methods, instances or classes between sub-interpreters,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4281 since import operations executed by such objects may affect the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4282 wrong (sub-)interpreter's dictionary of loaded modules. (XXX This is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4283 a hard-to-fix bug that will be addressed in a future release.)
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4284 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4285
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4286 \begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4287 Destroy the (sub-)interpreter represented by the given thread state.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4288 The given thread state must be the current thread state. See the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4289 discussion of thread states below. When the call returns, the current
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4290 thread state is \NULL{}. All thread states associated with this
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4291 interpreted are destroyed. (The global interpreter lock must be held
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4292 before calling this function and is still held when it returns.)
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4293 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will destroy all
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4294 sub-interpreters that haven't been explicitly destroyed at that point.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4295 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4296
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4297 \begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4298 This function should be called before
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4299 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4300 for the first time, if it is called at all. It tells the interpreter
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4301 the value of the \code{argv[0]} argument to the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4302 \cfunction{main()}\ttindex{main()} function of the program. This is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4303 used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some other
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4304 functions below to find the Python run-time libraries relative to the
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4305 interpreter executable. The default value is \code{'python'}. The
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4306 argument should point to a zero-terminated character string in static
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4307 storage whose contents will not change for the duration of the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4308 program's execution. No code in the Python interpreter will change
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4309 the contents of this storage.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4310 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4311
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4312 \begin{cfuncdesc}{char*}{Py_GetProgramName}{}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4313 Return the program name set with
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4314 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4315 default. The returned string points into static storage; the caller
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4316 should not modify its value.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4317 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4318
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4319 \begin{cfuncdesc}{char*}{Py_GetPrefix}{}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4320 Return the \emph{prefix} for installed platform-independent files. This
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4321 is derived through a number of complicated rules from the program name
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4322 set with \cfunction{Py_SetProgramName()} and some environment variables;
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4323 for example, if the program name is \code{'/usr/local/bin/python'},
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4324 the prefix is \code{'/usr/local'}. The returned string points into
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4325 static storage; the caller should not modify its value. This
8021 3b91affa333e In descriptions of Py_GetPrefix() and Py_GetExecPrefix(), make sure the Fred Drake <fdrake@acm.org> parents: 7923 diff changeset	4326 corresponds to the \makevar{prefix} variable in the top-level
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4327 \file{Makefile} and the \longprogramopt{prefix} argument to the
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4328 \program{configure} script at build time. The value is available to
7081 0baa2ab42ee9 Consistency: Fred Drake <fdrake@acm.org> parents: 7071 diff changeset	4329 Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4330 also the next function.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4331 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4332
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4333 \begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4334 Return the \emph{exec-prefix} for installed platform-\emph{de}pendent
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4335 files. This is derived through a number of complicated rules from the
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4336 program name set with \cfunction{Py_SetProgramName()} and some environment
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4337 variables; for example, if the program name is
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4338 \code{'/usr/local/bin/python'}, the exec-prefix is
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4339 \code{'/usr/local'}. The returned string points into static storage;
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4340 the caller should not modify its value. This corresponds to the
8021 3b91affa333e In descriptions of Py_GetPrefix() and Py_GetExecPrefix(), make sure the Fred Drake <fdrake@acm.org> parents: 7923 diff changeset	4341 \makevar{exec_prefix} variable in the top-level \file{Makefile} and the
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4342 \longprogramopt{exec-prefix} argument to the
11453 a05a05602902 Missed a couple of program options that had been marked by \code. Fred Drake <fdrake@acm.org> parents: 11451 diff changeset	4343 \program{configure} script at build time. The value is available to
a05a05602902 Missed a couple of program options that had been marked by \code. Fred Drake <fdrake@acm.org> parents: 11451 diff changeset	4344 Python code as \code{sys.exec_prefix}. It is only useful on \UNIX{}.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4345
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4346 Background: The exec-prefix differs from the prefix when platform
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4347 dependent files (such as executables and shared libraries) are
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4348 installed in a different directory tree. In a typical installation,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4349 platform dependent files may be installed in the
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4350 \file{/usr/local/plat} subtree while platform independent may be
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4351 installed in \file{/usr/local}.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4352
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4353 Generally speaking, a platform is a combination of hardware and
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4354 software families, e.g. Sparc machines running the Solaris 2.x
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4355 operating system are considered the same platform, but Intel machines
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4356 running Solaris 2.x are another platform, and Intel machines running
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4357 Linux are yet another platform. Different major revisions of the same
7081 0baa2ab42ee9 Consistency: Fred Drake <fdrake@acm.org> parents: 7071 diff changeset	4358 operating system generally also form different platforms. Non-\UNIX{}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4359 operating systems are a different story; the installation strategies
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4360 on those systems are so different that the prefix and exec-prefix are
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4361 meaningless, and set to the empty string. Note that compiled Python
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4362 bytecode files are platform independent (but not independent from the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4363 Python version by which they were compiled!).
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4364
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4365 System administrators will know how to configure the \program{mount} or
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4366 \program{automount} programs to share \file{/usr/local} between platforms
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4367 while having \file{/usr/local/plat} be a different filesystem for each
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4368 platform.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4369 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4370
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4371 \begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4372 Return the full program name of the Python executable; this is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4373 computed as a side-effect of deriving the default module search path
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4374 from the program name (set by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4375 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()} above).
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4376 The returned string points into static storage; the caller should not
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4377 modify its value. The value is available to Python code as
6382 16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for Guido van Rossum <guido@python.org> parents: 6126 diff changeset	4378 \code{sys.executable}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4379 \withsubitem{(in module sys)}{\ttindex{executable}}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4380 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4381
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4382 \begin{cfuncdesc}{char*}{Py_GetPath}{}
7310 6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4383 \indexiii{module}{search}{path}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4384 Return the default module search path; this is computed from the
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4385 program name (set by \cfunction{Py_SetProgramName()} above) and some
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4386 environment variables. The returned string consists of a series of
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4387 directory names separated by a platform dependent delimiter character.
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4388 The delimiter character is \character{:} on \UNIX{}, \character{;} on
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4389 DOS/Windows, and \character{\e n} (the \ASCII{} newline character) on
7271 0061d3916ae4 "ASCII" --> "\ASCII{}" Fred Drake <fdrake@acm.org> parents: 7269 diff changeset	4390 Macintosh. The returned string points into static storage; the caller
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4391 should not modify its value. The value is available to Python code
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4392 as the list \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4393 which may be modified to change the future search path for loaded
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4394 modules.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4395
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4396 % XXX should give the exact rules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4397 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4398
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4399 \begin{cfuncdesc}{const char*}{Py_GetVersion}{}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4400 Return the version of this Python interpreter. This is a string that
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4401 looks something like
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4402
6074 5e5e54a6dba6 Fixes to make it pass latex without complaints. Guido van Rossum <guido@python.org> parents: 6041 diff changeset	4403 \begin{verbatim}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4404 "1.5 (#67, Dec 31 1997, 22:34:28) [GCC 2.7.2.2]"
6074 5e5e54a6dba6 Fixes to make it pass latex without complaints. Guido van Rossum <guido@python.org> parents: 6041 diff changeset	4405 \end{verbatim}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4406
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4407 The first word (up to the first space character) is the current Python
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4408 version; the first three characters are the major and minor version
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4409 separated by a period. The returned string points into static storage;
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4410 the caller should not modify its value. The value is available to
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4411 Python code as the list \code{sys.version}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4412 \withsubitem{(in module sys)}{\ttindex{version}}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4413 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4414
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4415 \begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
7081 0baa2ab42ee9 Consistency: Fred Drake <fdrake@acm.org> parents: 7071 diff changeset	4416 Return the platform identifier for the current platform. On \UNIX{},
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4417 this is formed from the ``official'' name of the operating system,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4418 converted to lower case, followed by the major revision number; e.g.,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4419 for Solaris 2.x, which is also known as SunOS 5.x, the value is
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4420 \code{'sunos5'}. On Macintosh, it is \code{'mac'}. On Windows, it
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4421 is \code{'win'}. The returned string points into static storage;
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4422 the caller should not modify its value. The value is available to
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4423 Python code as \code{sys.platform}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4424 \withsubitem{(in module sys)}{\ttindex{platform}}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4425 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4426
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4427 \begin{cfuncdesc}{const char*}{Py_GetCopyright}{}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4428 Return the official copyright string for the current Python version,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4429 for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4430
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	4431 \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4432
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4433 The returned string points into static storage; the caller should not
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4434 modify its value. The value is available to Python code as the list
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4435 \code{sys.copyright}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4436 \withsubitem{(in module sys)}{\ttindex{copyright}}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4437 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4438
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4439 \begin{cfuncdesc}{const char*}{Py_GetCompiler}{}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4440 Return an indication of the compiler used to build the current Python
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4441 version, in square brackets, for example:
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4442
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4443 \begin{verbatim}
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4444 "[GCC 2.7.2.2]"
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4445 \end{verbatim}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4446
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4447 The returned string points into static storage; the caller should not
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4448 modify its value. The value is available to Python code as part of
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4449 the variable \code{sys.version}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4450 \withsubitem{(in module sys)}{\ttindex{version}}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4451 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4452
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4453 \begin{cfuncdesc}{const char*}{Py_GetBuildInfo}{}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4454 Return information about the sequence number and build date and time
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4455 of the current Python interpreter instance, for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4456
6074 5e5e54a6dba6 Fixes to make it pass latex without complaints. Guido van Rossum <guido@python.org> parents: 6041 diff changeset	4457 \begin{verbatim}
5e5e54a6dba6 Fixes to make it pass latex without complaints. Guido van Rossum <guido@python.org> parents: 6041 diff changeset	4458 "#67, Aug 1 1997, 22:34:28"
5e5e54a6dba6 Fixes to make it pass latex without complaints. Guido van Rossum <guido@python.org> parents: 6041 diff changeset	4459 \end{verbatim}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4460
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4461 The returned string points into static storage; the caller should not
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4462 modify its value. The value is available to Python code as part of
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4463 the variable \code{sys.version}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4464 \withsubitem{(in module sys)}{\ttindex{version}}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4465 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4466
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4467 \begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4468 Set \code{sys.argv} based on \var{argc} and \var{argv}. These
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4469 parameters are similar to those passed to the program's
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4470 \cfunction{main()}\ttindex{main()} function with the difference that
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4471 the first entry should refer to the script file to be executed rather
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4472 than the executable hosting the Python interpreter. If there isn't a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4473 script that will be run, the first entry in \var{argv} can be an empty
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4474 string. If this function fails to initialize \code{sys.argv}, a fatal
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4475 condition is signalled using
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4476 \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4477 \withsubitem{(in module sys)}{\ttindex{argv}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4478 % XXX impl. doesn't seem consistent in allowing 0/NULL for the params;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4479 % check w/ Guido.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4480 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4481
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4482 % XXX Other PySys thingies (doesn't really belong in this chapter)
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4483
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4484 \section{Thread State and the Global Interpreter Lock
ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	4485 \label{threads}}
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4486
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4487 \index{global interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4488 \index{interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4489 \index{lock, interpreter}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4490
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4491 The Python interpreter is not fully thread safe. In order to support
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4492 multi-threaded Python programs, there's a global lock that must be
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4493 held by the current thread before it can safely access Python objects.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4494 Without the lock, even the simplest operations could cause problems in
7422 2d508822e7f6 Fixed typo reported by Vladimir Marangozov <Vladimir.Marangozov@imag.fr>. Fred Drake <fdrake@acm.org> parents: 7314 diff changeset	4495 a multi-threaded program: for example, when two threads simultaneously
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4496 increment the reference count of the same object, the reference count
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4497 could end up being incremented only once instead of twice.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4498
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4499 Therefore, the rule exists that only the thread that has acquired the
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4500 global interpreter lock may operate on Python objects or call Python/C
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4501 API functions. In order to support multi-threaded Python programs,
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4502 the interpreter regularly releases and reacquires the lock --- by
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4503 default, every ten bytecode instructions (this can be changed with
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4504 \withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4505 \function{sys.setcheckinterval()}). The lock is also released and
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4506 reacquired around potentially blocking I/O operations like reading or
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4507 writing a file, so that other threads can run while the thread that
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4508 requests the I/O is waiting for the I/O operation to complete.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4509
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4510 The Python interpreter needs to keep some bookkeeping information
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4511 separate per thread --- for this it uses a data structure called
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4512 \ctype{PyThreadState}\ttindex{PyThreadState}. This is new in Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4513 1.5; in earlier versions, such state was stored in global variables,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4514 and switching threads could cause problems. In particular, exception
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4515 handling is now thread safe, when the application uses
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4516 \withsubitem{(in module sys)}{\ttindex{exc_info()}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4517 \function{sys.exc_info()} to access the exception last raised in the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4518 current thread.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4519
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4520 There's one global variable left, however: the pointer to the current
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4521 \ctype{PyThreadState}\ttindex{PyThreadState} structure. While most
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4522 thread packages have a way to store ``per-thread global data,''
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4523 Python's internal platform independent thread abstraction doesn't
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4524 support this yet. Therefore, the current thread state must be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4525 manipulated explicitly.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4526
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4527 This is easy enough in most cases. Most code manipulating the global
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4528 interpreter lock has the following simple structure:
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4529
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	4530 \begin{verbatim}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4531 Save the thread state in a local variable.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4532 Release the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4533 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4534 Reacquire the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4535 Restore the thread state from the local variable.
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	4536 \end{verbatim}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4537
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4538 This is so common that a pair of macros exists to simplify it:
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4539
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	4540 \begin{verbatim}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4541 Py_BEGIN_ALLOW_THREADS
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4542 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4543 Py_END_ALLOW_THREADS
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	4544 \end{verbatim}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4545
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4546 The \code{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS} macro
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4547 opens a new block and declares a hidden local variable; the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4548 \code{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS} macro closes
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4549 the block. Another advantage of using these two macros is that when
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4550 Python is compiled without thread support, they are defined empty,
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4551 thus saving the thread state and lock manipulations.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4552
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4553 When thread support is enabled, the block above expands to the
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4554 following code:
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4555
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	4556 \begin{verbatim}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4557 PyThreadState *_save;
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4558
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4559 _save = PyEval_SaveThread();
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4560 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4561 PyEval_RestoreThread(_save);
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	4562 \end{verbatim}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4563
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4564 Using even lower level primitives, we can get roughly the same effect
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4565 as follows:
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4566
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	4567 \begin{verbatim}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4568 PyThreadState *_save;
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4569
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4570 _save = PyThreadState_Swap(NULL);
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4571 PyEval_ReleaseLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4572 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4573 PyEval_AcquireLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4574 PyThreadState_Swap(_save);
6417 4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode Guido van Rossum <guido@python.org> parents: 6390 diff changeset	4575 \end{verbatim}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4576
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4577 There are some subtle differences; in particular,
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4578 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4579 and restores the value of the global variable
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4580 \cdata{errno}\ttindex{errno}, since the lock manipulation does not
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4581 guarantee that \cdata{errno} is left alone. Also, when thread support
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4582 is disabled,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4583 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4584 \cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4585 case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4586 \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are not
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4587 available. This is done so that dynamically loaded extensions
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4588 compiled with thread support enabled can be loaded by an interpreter
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4589 that was compiled with disabled thread support.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4590
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4591 The global interpreter lock is used to protect the pointer to the
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4592 current thread state. When releasing the lock and saving the thread
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4593 state, the current thread state pointer must be retrieved before the
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4594 lock is released (since another thread could immediately acquire the
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4595 lock and store its own thread state in the global variable).
14926 76c1e40c5c5d Reversely --> Conversely Fred Drake <fdrake@acm.org> parents: 14870 diff changeset	4596 Conversely, when acquiring the lock and restoring the thread state,
76c1e40c5c5d Reversely --> Conversely Fred Drake <fdrake@acm.org> parents: 14870 diff changeset	4597 the lock must be acquired before storing the thread state pointer.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4598
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4599 Why am I going on with so much detail about this? Because when
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4600 threads are created from C, they don't have the global interpreter
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4601 lock, nor is there a thread state data structure for them. Such
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4602 threads must bootstrap themselves into existence, by first creating a
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4603 thread state data structure, then acquiring the lock, and finally
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4604 storing their thread state pointer, before they can start using the
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4605 Python/C API. When they are done, they should reset the thread state
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4606 pointer, release the lock, and finally free their thread state data
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4607 structure.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4608
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4609 When creating a thread data structure, you need to provide an
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4610 interpreter state data structure. The interpreter state data
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4611 structure hold global data that is shared by all threads in an
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4612 interpreter, for example the module administration
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4613 (\code{sys.modules}). Depending on your needs, you can either create
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4614 a new interpreter state data structure, or share the interpreter state
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4615 data structure used by the Python main thread (to access the latter,
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4616 you must obtain the thread state and access its \member{interp} member;
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4617 this must be done by a thread that is created by Python or by the main
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4618 thread after Python is initialized).
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4619
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4620
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4621 \begin{ctypedesc}{PyInterpreterState}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4622 This data structure represents the state shared by a number of
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4623 cooperating threads. Threads belonging to the same interpreter
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4624 share their module administration and a few other internal items.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4625 There are no public members in this structure.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4626
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4627 Threads belonging to different interpreters initially share nothing,
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4628 except process state like available memory, open file descriptors and
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4629 such. The global interpreter lock is also shared by all threads,
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4630 regardless of to which interpreter they belong.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4631 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4632
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4633 \begin{ctypedesc}{PyThreadState}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4634 This data structure represents the state of a single thread. The only
8120 068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4635 public data member is \ctype{PyInterpreterState *}\member{interp},
068fea15cbcd Convert recent additions to use new, "logical" markup. Fred Drake <fdrake@acm.org> parents: 8109 diff changeset	4636 which points to this thread's interpreter state.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4637 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4638
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4639 \begin{cfuncdesc}{void}{PyEval_InitThreads}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4640 Initialize and acquire the global interpreter lock. It should be
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4641 called in the main thread before creating a second thread or engaging
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4642 in any other thread operations such as
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4643 \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4644 \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4645 It is not needed before calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4646 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4647 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4648
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4649 This is a no-op when called for a second time. It is safe to call
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4650 this function before calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4651 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4652
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4653 When only the main thread exists, no lock operations are needed. This
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4654 is a common situation (most Python programs do not use threads), and
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4655 the lock operations slow the interpreter down a bit. Therefore, the
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4656 lock is not created initially. This situation is equivalent to having
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4657 acquired the lock: when there is only a single thread, all object
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4658 accesses are safe. Therefore, when this function initializes the
7310 6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4659 lock, it also acquires it. Before the Python
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4660 \module{thread}\refbimodindex{thread} module creates a new thread,
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4661 knowing that either it has the lock or the lock hasn't been created
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4662 yet, it calls \cfunction{PyEval_InitThreads()}. When this call
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4663 returns, it is guaranteed that the lock has been created and that it
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent Fred Drake <fdrake@acm.org> parents: 7309 diff changeset	4664 has acquired it.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4665
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4666 It is \strong{not} safe to call this function when it is unknown which
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4667 thread (if any) currently has the global interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4668
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4669 This function is not available when thread support is disabled at
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4670 compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4671 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4672
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4673 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4674 Acquire the global interpreter lock. The lock must have been created
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4675 earlier. If this thread already has the lock, a deadlock ensues.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4676 This function is not available when thread support is disabled at
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4677 compile time.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4678 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4679
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4680 \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4681 Release the global interpreter lock. The lock must have been created
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4682 earlier. This function is not available when thread support is
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4683 disabled at compile time.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4684 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4685
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4686 \begin{cfuncdesc}{void}{PyEval_AcquireThread}{PyThreadState *tstate}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4687 Acquire the global interpreter lock and then set the current thread
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4688 state to \var{tstate}, which should not be \NULL{}. The lock must
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4689 have been created earlier. If this thread already has the lock,
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4690 deadlock ensues. This function is not available when thread support
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4691 is disabled at compile time.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4692 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4693
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4694 \begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4695 Reset the current thread state to \NULL{} and release the global
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4696 interpreter lock. The lock must have been created earlier and must be
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4697 held by the current thread. The \var{tstate} argument, which must not
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4698 be \NULL{}, is only used to check that it represents the current
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4699 thread state --- if it isn't, a fatal error is reported. This
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4700 function is not available when thread support is disabled at compile
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4701 time.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4702 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4703
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4704 \begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4705 Release the interpreter lock (if it has been created and thread
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4706 support is enabled) and reset the thread state to \NULL{},
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4707 returning the previous thread state (which is not \NULL{}). If
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4708 the lock has been created, the current thread must have acquired it.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4709 (This function is available even when thread support is disabled at
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4710 compile time.)
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4711 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4712
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4713 \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4714 Acquire the interpreter lock (if it has been created and thread
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4715 support is enabled) and set the thread state to \var{tstate}, which
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4716 must not be \NULL{}. If the lock has been created, the current
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4717 thread must not have acquired it, otherwise deadlock ensues. (This
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4718 function is available even when thread support is disabled at compile
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4719 time.)
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4720 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4721
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4722 The following macros are normally used without a trailing semicolon;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4723 look for example usage in the Python source distribution.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4724
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4725 \begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4726 This macro expands to
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4727 \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4728 Note that it contains an opening brace; it must be matched with a
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4729 following \code{Py_END_ALLOW_THREADS} macro. See above for further
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4730 discussion of this macro. It is a no-op when thread support is
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4731 disabled at compile time.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4732 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4733
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4734 \begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4735 This macro expands to
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4736 \samp{PyEval_RestoreThread(_save); \}}.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4737 Note that it contains a closing brace; it must be matched with an
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4738 earlier \code{Py_BEGIN_ALLOW_THREADS} macro. See above for further
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4739 discussion of this macro. It is a no-op when thread support is
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4740 disabled at compile time.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4741 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4742
18438 05c49346b68b Fix for SF bug #436525, reported by Greg Kochanski: Thomas Wouters <thomas@python.org> parents: 18192 diff changeset	4743 \begin{csimplemacrodesc}{Py_BLOCK_THREADS}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	4744 This macro expands to \samp{PyEval_RestoreThread(_save);}: it
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4745 is equivalent to \code{Py_END_ALLOW_THREADS} without the closing
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4746 brace. It is a no-op when thread support is disabled at compile
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4747 time.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4748 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4749
18438 05c49346b68b Fix for SF bug #436525, reported by Greg Kochanski: Thomas Wouters <thomas@python.org> parents: 18192 diff changeset	4750 \begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	4751 This macro expands to \samp{_save = PyEval_SaveThread();}: it is
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4752 equivalent to \code{Py_BEGIN_ALLOW_THREADS} without the opening brace
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4753 and variable declaration. It is a no-op when thread support is
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4754 disabled at compile time.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4755 \end{csimplemacrodesc}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4756
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4757 All of the following functions are only available when thread support
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4758 is enabled at compile time, and must be called only when the
7314 d23bb969e63a Removed various "(New in 1.5a?!)" constructs. Other notes pertaining to Fred Drake <fdrake@acm.org> parents: 7310 diff changeset	4759 interpreter lock has been created.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4760
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4761 \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{}
8881 febca6b1827d Clarify that the Python interpreter lock need not be held by Guido van Rossum <guido@python.org> parents: 8782 diff changeset	4762 Create a new interpreter state object. The interpreter lock need not
febca6b1827d Clarify that the Python interpreter lock need not be held by Guido van Rossum <guido@python.org> parents: 8782 diff changeset	4763 be held, but may be held if it is necessary to serialize calls to this
febca6b1827d Clarify that the Python interpreter lock need not be held by Guido van Rossum <guido@python.org> parents: 8782 diff changeset	4764 function.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4765 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4766
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4767 \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4768 Reset all information in an interpreter state object. The interpreter
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4769 lock must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4770 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4771
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4772 \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4773 Destroy an interpreter state object. The interpreter lock need not be
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4774 held. The interpreter state must have been reset with a previous
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4775 call to \cfunction{PyInterpreterState_Clear()}.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4776 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4777
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4778 \begin{cfuncdesc}{PyThreadState}{PyThreadState_New}{PyInterpreterState interp}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4779 Create a new thread state object belonging to the given interpreter
8881 febca6b1827d Clarify that the Python interpreter lock need not be held by Guido van Rossum <guido@python.org> parents: 8782 diff changeset	4780 object. The interpreter lock need not be held, but may be held if it
febca6b1827d Clarify that the Python interpreter lock need not be held by Guido van Rossum <guido@python.org> parents: 8782 diff changeset	4781 is necessary to serialize calls to this function.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4782 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4783
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4784 \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4785 Reset all information in a thread state object. The interpreter lock
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4786 must be held.
6041 a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4787 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary) Guido van Rossum <guido@python.org> parents: 6040 diff changeset	4788
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4789 \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4790 Destroy a thread state object. The interpreter lock need not be
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4791 held. The thread state must have been reset with a previous
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	4792 call to \cfunction{PyThreadState_Clear()}.
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4793 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4794
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4795 \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4796 Return the current thread state. The interpreter lock must be held.
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4797 When the current thread state is \NULL{}, this issues a fatal
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	4798 error (so that the caller needn't check for \NULL{}).
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4799 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4800
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	4801 \begin{cfuncdesc}{PyThreadState}{PyThreadState_Swap}{PyThreadState tstate}
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4802 Swap the current thread state with the thread state given by the
6653 c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what Guido van Rossum <guido@python.org> parents: 6480 diff changeset	4803 argument \var{tstate}, which may be \NULL{}. The interpreter lock
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4804 must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4805 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4806
17877 13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	4807 \begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	4808 Return a dictionary in which extensions can store thread-specific
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	4809 state information. Each extension should use a unique key to use to
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	4810 store state in the dictionary. If this function returns \NULL, an
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	4811 exception has been raised and the caller should allow it to
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	4812 propogate.
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	4813 \end{cfuncdesc}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict(). Fred Drake <fdrake@acm.org> parents: 17875 diff changeset	4814
6390 a2df3c9e5f43 Done with tread state descriptions. Sigh! Guido van Rossum <guido@python.org> parents: 6382 diff changeset	4815
18671 38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4816 \section{Profiling and Tracing \label{profiling}}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4817
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4818 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4819
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4820 The Python interpreter provides some low-level support for attaching
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4821 profiling and execution tracing facilities. These are used for
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4822 profiling, debugging, and coverage analysis tools.
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4823
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4824 Starting with Python 2.2, the implementation of this facility was
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4825 substantially revised, and an interface from C was added. This C
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4826 interface allows the profiling or tracing code to avoid the overhead
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4827 of calling through Python-level callable objects, making a direct C
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4828 function call instead. The essential attributes of the facility have
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4829 not changed; the interface allows trace functions to be installed
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4830 per-thread, and the basic events reported to the trace function are
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4831 the same as had been reported to the Python-level trace functions in
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4832 previous versions.
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4833
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4834 \begin{ctypedesc}[Py_tracefunc]{int (Py_tracefunc)(PyObject obj,
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4835 PyFrameObject *frame, int what,
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4836 PyObject *arg)}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4837 The type of the trace function registered using
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4838 \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4839 The first parameter is the object passed to the registration
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4840 function,
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4841 \end{ctypedesc}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4842
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4843 \begin{cvardesc}{int}{PyTrace_CALL}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4844 The value of the \var{what} parameter to a \ctype{Py_tracefunc}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4845 function when a new function or method call is being reported.
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4846 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4847
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4848 \begin{cvardesc}{int}{PyTrace_EXCEPT}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4849 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4850
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4851 \begin{cvardesc}{int}{PyTrace_LINE}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4852 The value passed as the \var{what} parameter to a trace function
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4853 (but not a profiling function) when a line-number event is being
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4854 reported.
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4855 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4856
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4857 \begin{cvardesc}{int}{PyTrace_RETURN}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4858 The value for the \var{what} parameter to \ctype{Py_tracefunc}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4859 functions when a call is returning without propogating an exception.
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4860 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4861
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4862 \begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj}
18944 a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	4863 Set the profiler function to \var{func}. The \var{obj} parameter is
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	4864 passed to the function as its first parameter, and may be any Python
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	4865 object, or \NULL. If the profile function needs to maintain state,
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	4866 using a different value for \var{obj} for each thread provides a
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	4867 convenient and thread-safe place to store it. The profile function
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	4868 is called for all monitored events except the line-number events.
18671 38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4869 \end{cfuncdesc}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4870
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4871 \begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
18944 a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	4872 Set the the tracing function to \var{func}. This is similar to
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	4873 \cfunction{PyEval_SetProfile()}, except the tracing function does
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	4874 receive line-number events.
18671 38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4875 \end{cfuncdesc}
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4876
38206f29b0fc Adding what's done of the documentation for the new profiling & Fred Drake <fdrake@acm.org> parents: 18576 diff changeset	4877
19076 f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4878 \section{Advanced Debugger Support \label{advanced-debugging}}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4879 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4880
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4881 These functions are only intended to be used by advanced debugging
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4882 tools.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4883
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4884 \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4885 Return the interpreter state object at the head of the list of all
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4886 such objects.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4887 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4888 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4889
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4890 \begin{cfuncdesc}{PyInterpreterState}{PyInterpreterState_Next}{PyInterpreterState interp}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4891 Return the next interpreter state object after \var{interp} from the
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4892 list of all such objects.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4893 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4894 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4895
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4896 \begin{cfuncdesc}{PyThreadState }{PyInterpreterState_ThreadHead}{PyInterpreterState interp}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4897 Return the a pointer to the first \ctype{PyThreadState} object in the
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4898 list of threads associated with the interpreter \var{interp}.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4899 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4900 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4901
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4902 \begin{cfuncdesc}{PyThreadState}{PyThreadState_Next}{PyThreadState tstate}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4903 Return the next thread state object after \var{tstate} from the list
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4904 of all such objects belonging to the same \ctype{PyInterpreterState}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4905 object.
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4906 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4907 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4908
f75125ead0a2 Added documentation for PyNumber_FloorDivide(), PyNumber_TrueDivide(), Fred Drake <fdrake@acm.org> parents: 18944 diff changeset	4909
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4910 \chapter{Memory Management \label{memory}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4911 \sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4912
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4913
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4914 \section{Overview \label{memoryOverview}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4915
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4916 Memory management in Python involves a private heap containing all
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4917 Python objects and data structures. The management of this private
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4918 heap is ensured internally by the \emph{Python memory manager}. The
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4919 Python memory manager has different components which deal with various
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4920 dynamic storage management aspects, like sharing, segmentation,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4921 preallocation or caching.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4922
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4923 At the lowest level, a raw memory allocator ensures that there is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4924 enough room in the private heap for storing all Python-related data
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4925 by interacting with the memory manager of the operating system. On top
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4926 of the raw memory allocator, several object-specific allocators
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4927 operate on the same heap and implement distinct memory management
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4928 policies adapted to the peculiarities of every object type. For
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4929 example, integer objects are managed differently within the heap than
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4930 strings, tuples or dictionaries because integers imply different
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4931 storage requirements and speed/space tradeoffs. The Python memory
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4932 manager thus delegates some of the work to the object-specific
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4933 allocators, but ensures that the latter operate within the bounds of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4934 the private heap.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4935
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4936 It is important to understand that the management of the Python heap
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4937 is performed by the interpreter itself and that the user has no
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4938 control on it, even if she regularly manipulates object pointers to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4939 memory blocks inside that heap. The allocation of heap space for
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4940 Python objects and other internal buffers is performed on demand by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4941 the Python memory manager through the Python/C API functions listed in
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4942 this document.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4943
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4944 To avoid memory corruption, extension writers should never try to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4945 operate on Python objects with the functions exported by the C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4946 library: \cfunction{malloc()}\ttindex{malloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4947 \cfunction{calloc()}\ttindex{calloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4948 \cfunction{realloc()}\ttindex{realloc()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4949 \cfunction{free()}\ttindex{free()}. This will result in
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4950 mixed calls between the C allocator and the Python memory manager
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4951 with fatal consequences, because they implement different algorithms
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4952 and operate on different heaps. However, one may safely allocate and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4953 release memory blocks with the C library allocator for individual
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4954 purposes, as shown in the following example:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4955
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4956 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4957 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4958 char buf = (char ) malloc(BUFSIZ); /* for I/O */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4959
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4960 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4961 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4962 ...Do some I/O operation involving buf...
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4963 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4964 free(buf); /* malloc'ed */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4965 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4966 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4967
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4968 In this example, the memory request for the I/O buffer is handled by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4969 the C library allocator. The Python memory manager is involved only
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4970 in the allocation of the string object returned as a result.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4971
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4972 In most situations, however, it is recommended to allocate memory from
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4973 the Python heap specifically because the latter is under control of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4974 the Python memory manager. For example, this is required when the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4975 interpreter is extended with new object types written in C. Another
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4976 reason for using the Python heap is the desire to \emph{inform} the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4977 Python memory manager about the memory needs of the extension module.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4978 Even when the requested memory is used exclusively for internal,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4979 highly-specific purposes, delegating all memory requests to the Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4980 memory manager causes the interpreter to have a more accurate image of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4981 its memory footprint as a whole. Consequently, under certain
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4982 circumstances, the Python memory manager may or may not trigger
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4983 appropriate actions, like garbage collection, memory compaction or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4984 other preventive procedures. Note that by using the C library
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4985 allocator as shown in the previous example, the allocated memory for
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4986 the I/O buffer escapes completely the Python memory manager.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4987
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4988
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4989 \section{Memory Interface \label{memoryInterface}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4990
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4991 The following function sets, modeled after the ANSI C standard, are
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4992 available for allocating and releasing memory from the Python heap:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4993
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4994
13920 d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C. Fred Drake <fdrake@acm.org> parents: 13592 diff changeset	4995 \begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n}
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C. Fred Drake <fdrake@acm.org> parents: 13592 diff changeset	4996 Allocates \var{n} bytes and returns a pointer of type \ctype{void*} to
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	4997 the allocated memory, or \NULL{} if the request fails. Requesting zero
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	4998 bytes returns a non-\NULL{} pointer.
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	4999 The memory will not have been initialized in any way.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5000 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5001
13920 d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C. Fred Drake <fdrake@acm.org> parents: 13592 diff changeset	5002 \begin{cfuncdesc}{void}{PyMem_Realloc}{void p, size_t n}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5003 Resizes the memory block pointed to by \var{p} to \var{n} bytes. The
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5004 contents will be unchanged to the minimum of the old and the new
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5005 sizes. If \var{p} is \NULL{}, the call is equivalent to
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5006 \cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5007 memory block is resized but is not freed, and the returned pointer is
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5008 non-\NULL{}. Unless \var{p} is \NULL{}, it must have been returned by
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5009 a previous call to \cfunction{PyMem_Malloc()} or
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5010 \cfunction{PyMem_Realloc()}.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5011 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5012
13920 d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C. Fred Drake <fdrake@acm.org> parents: 13592 diff changeset	5013 \begin{cfuncdesc}{void}{PyMem_Free}{void *p}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5014 Frees the memory block pointed to by \var{p}, which must have been
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5015 returned by a previous call to \cfunction{PyMem_Malloc()} or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5016 \cfunction{PyMem_Realloc()}. Otherwise, or if
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5017 \cfunction{PyMem_Free(p)} has been called before, undefined behaviour
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5018 occurs. If \var{p} is \NULL{}, no operation is performed.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5019 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5020
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5021 The following type-oriented macros are provided for convenience. Note
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5022 that \var{TYPE} refers to any C type.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5023
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5024 \begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5025 Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} *
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5026 sizeof(\var{TYPE}))} bytes of memory. Returns a pointer cast to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5027 \ctype{\var{TYPE}*}.
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5028 The memory will not have been initialized in any way.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5029 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5030
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5031 \begin{cfuncdesc}{\var{TYPE}}{PyMem_Resize}{void p, TYPE, size_t n}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5032 Same as \cfunction{PyMem_Realloc()}, but the memory block is resized
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5033 to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5034 cast to \ctype{\var{TYPE}*}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5035 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5036
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5037 \begin{cfuncdesc}{void}{PyMem_Del}{void *p}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5038 Same as \cfunction{PyMem_Free()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5039 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5040
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5041 In addition, the following macro sets are provided for calling the
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5042 Python memory allocator directly, without involving the C API functions
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5043 listed above. However, note that their use does not preserve binary
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5044 compatibility accross Python versions and is therefore deprecated in
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5045 extension modules.
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5046
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5047 \cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}.
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5048
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5049 \cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}.
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5050
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5051
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5052 \section{Examples \label{memoryExamples}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5053
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5054 Here is the example from section \ref{memoryOverview}, rewritten so
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5055 that the I/O buffer is allocated from the Python heap by using the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5056 first function set:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5057
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5058 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5059 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5060 char buf = (char ) PyMem_Malloc(BUFSIZ); /* for I/O */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5061
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5062 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5063 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5064 /* ...Do some I/O operation involving buf... */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5065 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5066 PyMem_Free(buf); /* allocated with PyMem_Malloc */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5067 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5068 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5069
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5070 The same code using the type-oriented function set:
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5071
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5072 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5073 PyObject *res;
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5074 char buf = PyMem_New(char, BUFSIZ); / for I/O */
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5075
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5076 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5077 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5078 /* ...Do some I/O operation involving buf... */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5079 res = PyString_FromString(buf);
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5080 PyMem_Del(buf); /* allocated with PyMem_New */
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5081 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5082 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5083
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5084 Note that in the two examples above, the buffer is always
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5085 manipulated via functions belonging to the same set. Indeed, it
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5086 is required to use the same memory API family for a given
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5087 memory block, so that the risk of mixing different allocators is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5088 reduced to a minimum. The following code sequence contains two errors,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5089 one of which is labeled as \emph{fatal} because it mixes two different
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5090 allocators operating on different heaps.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5091
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5092 \begin{verbatim}
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5093 char *buf1 = PyMem_New(char, BUFSIZ);
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5094 char buf2 = (char ) malloc(BUFSIZ);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5095 char buf3 = (char ) PyMem_Malloc(BUFSIZ);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5096 ...
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5097 PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5098 free(buf2); /* Right -- allocated via malloc() */
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5099 free(buf1); /* Fatal -- should be PyMem_Del() */
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5100 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5101
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5102 In addition to the functions aimed at handling raw memory blocks from
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5103 the Python heap, objects in Python are allocated and released with
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5104 \cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5105 \cfunction{PyObject_Del()}, or with their corresponding macros
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5106 \cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and
13217 e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2. Fred Drake <fdrake@acm.org> parents: 13150 diff changeset	5107 \cfunction{PyObject_DEL()}.
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2. Fred Drake <fdrake@acm.org> parents: 13150 diff changeset	5108
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2. Fred Drake <fdrake@acm.org> parents: 13150 diff changeset	5109 These will be explained in the next chapter on defining and
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2. Fred Drake <fdrake@acm.org> parents: 13150 diff changeset	5110 implementing new object types in C.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5111
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5112
10163 ddf861d84bbb Markup nits. Fred Drake <fdrake@acm.org> parents: 9931 diff changeset	5113 \chapter{Defining New Object Types \label{newTypes}}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	5114
18785 b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	5115
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	5116 \section{Allocating Objects on the Heap
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	5117 \label{allocating-objects}}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple Fred Drake <fdrake@acm.org> parents: 18671 diff changeset	5118
7782 7fc32a66255a Markup consistency & nits. Fred Drake <fdrake@acm.org> parents: 7708 diff changeset	5119 \begin{cfuncdesc}{PyObject}{_PyObject_New}{PyTypeObject type}
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	5120 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	5121
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5122 \begin{cfuncdesc}{PyVarObject}{_PyObject_NewVar}{PyTypeObject type, int size}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5123 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5124
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5125 \begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5126 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5127
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5128 \begin{cfuncdesc}{PyObject}{PyObject_Init}{PyObject op,
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5129 PyTypeObject *type}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5130 Initialize a newly-allocated object \var{op} with its type and
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5131 initial reference. Returns the initialized object. If \var{type}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5132 indicates that the object participates in the cyclic garbage
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5133 detector, it it added to the detector's set of observed objects.
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5134 Other fields of the object are not affected.
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5135 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5136
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5137 \begin{cfuncdesc}{PyVarObject}{PyObject_InitVar}{PyVarObject op,
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5138 PyTypeObject *type, int size}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5139 This does everything \cfunction{PyObject_Init()} does, and also
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5140 initializes the length information for a variable-size object.
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5141 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5142
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5143 \begin{cfuncdesc}{\var{TYPE}}{PyObject_New}{TYPE, PyTypeObject type}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5144 Allocate a new Python object using the C structure type \var{TYPE}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5145 and the Python type object \var{type}. Fields not defined by the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5146 Python object header are not initialized; the object's reference
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5147 count will be one. The size of the memory
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5148 allocation is determined from the \member{tp_basicsize} field of the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5149 type object.
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5150 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5151
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5152 \begin{cfuncdesc}{\var{TYPE}}{PyObject_NewVar}{TYPE, PyTypeObject type,
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5153 int size}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5154 Allocate a new Python object using the C structure type \var{TYPE}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5155 and the Python type object \var{type}. Fields not defined by the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5156 Python object header are not initialized. The allocated memory
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5157 allows for the \var{TYPE} structure plus \var{size} fields of the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5158 size given by the \member{tp_itemsize} field of \var{type}. This is
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5159 useful for implementing objects like tuples, which are able to
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5160 determine their size at construction time. Embedding the array of
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5161 fields into the same allocation decreases the number of allocations,
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5162 improving the memory management efficiency.
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5163 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5164
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5165 \begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5166 Releases memory allocated to an object using
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5167 \cfunction{PyObject_New()} or \cfunction{PyObject_NewVar()}. This
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5168 is normally called from the \member{tp_dealloc} handler specified in
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5169 the object's type. The fields of the object should not be accessed
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5170 after this call as the memory is no longer a valid Python object.
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5171 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5172
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5173 \begin{cfuncdesc}{\var{TYPE}}{PyObject_NEW}{TYPE, PyTypeObject type}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5174 Macro version of \cfunction{PyObject_New()}, to gain performance at
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5175 the expense of safety. This does not check \var{type} for a \NULL{}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5176 value.
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5177 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5178
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5179 \begin{cfuncdesc}{\var{TYPE}}{PyObject_NEW_VAR}{TYPE, PyTypeObject type,
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5180 int size}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5181 Macro version of \cfunction{PyObject_NewVar()}, to gain performance
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5182 at the expense of safety. This does not check \var{type} for a
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5183 \NULL{} value.
14526 ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5184 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5185
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>: Fred Drake <fdrake@acm.org> parents: 14519 diff changeset	5186 \begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op}
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5187 Macro version of \cfunction{PyObject_Del()}.
7308 8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	5188 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff: Fred Drake <fdrake@acm.org> parents: 7278 diff changeset	5189
15444 7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5190 \begin{cfuncdesc}{PyObject}{Py_InitModule}{char name,
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5191 PyMethodDef *methods}
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5192 Create a new module object based on a name and table of functions,
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5193 returning the new module object.
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5194 \end{cfuncdesc}
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5195
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5196 \begin{cfuncdesc}{PyObject}{Py_InitModule3}{char name,
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5197 PyMethodDef *methods,
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5198 char *doc}
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5199 Create a new module object based on a name and table of functions,
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5200 returning the new module object. If \var{doc} is non-\NULL, it will
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5201 be used to define the docstring for the module.
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5202 \end{cfuncdesc}
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5203
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5204 \begin{cfuncdesc}{PyObject}{Py_InitModule4}{char name,
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5205 PyMethodDef *methods,
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5206 char doc, PyObject self,
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5207 int apiver}
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5208 Create a new module object based on a name and table of functions,
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5209 returning the new module object. If \var{doc} is non-\NULL, it will
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5210 be used to define the docstring for the module. If \var{self} is
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5211 non-\NULL, it will passed to the functions of the module as their
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5212 (otherwise \NULL) first parameter. (This was added as an
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5213 experimental feature, and there are no known uses in the current
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5214 version of Python.) For \var{apiver}, the only value which should
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5215 be passed is defined by the constant \constant{PYTHON_API_VERSION}.
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5216
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5217 \strong{Note:} Most uses of this function should probably be using
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5218 the \cfunction{Py_InitModule3()} instead; only use this if you are
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5219 sure you need it.
7e514f1fe31f Added documentation for the Py_InitModule() family of functions. Fred Drake <fdrake@acm.org>* parents: 15300 diff changeset	5220 \end{cfuncdesc}
8057 5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes. Guido van Rossum <guido@python.org> parents: 8029 diff changeset	5221
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5222 DL_IMPORT
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5223
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5224 \begin{cvardesc}{PyObject}{_Py_NoneStruct}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5225 Object which is visible in Python as \code{None}. This should only
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5226 be accessed using the \code{Py_None} macro, which evaluates to a
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5227 pointer to this object.
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5228 \end{cvardesc}
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5229
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5230
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5231 \section{Common Object Structures \label{common-structs}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5232
5588 53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5233 PyObject, PyVarObject
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5234
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5235 PyObject_HEAD, PyObject_HEAD_INIT, PyObject_VAR_HEAD
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5236
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5237 Typedefs:
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5238 unaryfunc, binaryfunc, ternaryfunc, inquiry, coercion, intargfunc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5239 intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5240 destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5241 setattrofunc, cmpfunc, reprfunc, hashfunc
53cdf94b652b Just another checkin for backup. Nothing substantial yet. Guido van Rossum <guido@python.org> parents: 5536 diff changeset	5242
12930 6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5243 \begin{ctypedesc}{PyCFunction}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5244 Type of the functions used to implement most Python callables in C.
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5245 \end{ctypedesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5246
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5247 \begin{ctypedesc}{PyMethodDef}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5248 Structure used to describe a method of an extension type. This
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5249 structure has four fields:
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5250
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5251 \begin{tableiii}{l\|l\|l}{member}{Field}{C Type}{Meaning}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5252 \lineiii{ml_name}{char *}{name of the method}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5253 \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5254 \lineiii{ml_flags}{int}{flag bits indicating how the call should be
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5255 constructed}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5256 \lineiii{ml_doc}{char *}{points to the contents of the docstring}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5257 \end{tableiii}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5258 \end{ctypedesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5259
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5260 \begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef[] table,
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5261 PyObject ob, char name}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5262 Return a bound method object for an extension type implemented in C.
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5263 This function also handles the special attribute \member{__methods__},
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5264 returning a list of all the method names defined in \var{table}.
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5265 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple(). Fred Drake <fdrake@acm.org> parents: 12355 diff changeset	5266
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5267
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5268 \section{Mapping Object Structures \label{mapping-structs}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5269
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5270 \begin{ctypedesc}{PyMappingMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5271 Structure used to hold pointers to the functions used to implement the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5272 mapping protocol for an extension type.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5273 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5274
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5275
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5276 \section{Number Object Structures \label{number-structs}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5277
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5278 \begin{ctypedesc}{PyNumberMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5279 Structure used to hold pointers to the functions an extension type
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5280 uses to implement the number protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5281 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5282
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5283
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5284 \section{Sequence Object Structures \label{sequence-structs}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5285
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5286 \begin{ctypedesc}{PySequenceMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5287 Structure used to hold pointers to the functions which an object uses
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5288 to implement the sequence protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5289 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5290
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5291
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5292 \section{Buffer Object Structures \label{buffer-structs}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5293 \sectionauthor{Greg J. Stein}{greg@lyra.org}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5294
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5295 The buffer interface exports a model where an object can expose its
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5296 internal data as a set of chunks of data, where each chunk is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5297 specified as a pointer/length pair. These chunks are called
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5298 \dfn{segments} and are presumed to be non-contiguous in memory.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5299
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5300 If an object does not export the buffer interface, then its
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5301 \member{tp_as_buffer} member in the \ctype{PyTypeObject} structure
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5302 should be \NULL{}. Otherwise, the \member{tp_as_buffer} will point to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5303 a \ctype{PyBufferProcs} structure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5304
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5305 \strong{Note:} It is very important that your
17118 f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5306 \ctype{PyTypeObject} structure uses \constant{Py_TPFLAGS_DEFAULT} for
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5307 the value of the \member{tp_flags} member rather than \code{0}. This
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5308 tells the Python runtime that your \ctype{PyBufferProcs} structure
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5309 contains the \member{bf_getcharbuffer} slot. Older versions of Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5310 did not have this member, so a new Python interpreter using an old
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5311 extension needs to be able to test for its presence before using it.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5312
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5313 \begin{ctypedesc}{PyBufferProcs}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5314 Structure used to hold the function pointers which define an
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5315 implementation of the buffer protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5316
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5317 The first slot is \member{bf_getreadbuffer}, of type
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5318 \ctype{getreadbufferproc}. If this slot is \NULL{}, then the object
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5319 does not support reading from the internal data. This is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5320 non-sensical, so implementors should fill this in, but callers should
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5321 test that the slot contains a non-\NULL{} value.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5322
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5323 The next slot is \member{bf_getwritebuffer} having type
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5324 \ctype{getwritebufferproc}. This slot may be \NULL{} if the object
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5325 does not allow writing into its returned buffers.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5326
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5327 The third slot is \member{bf_getsegcount}, with type
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5328 \ctype{getsegcountproc}. This slot must not be \NULL{} and is used to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5329 inform the caller how many segments the object contains. Simple
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5330 objects such as \ctype{PyString_Type} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5331 \ctype{PyBuffer_Type} objects contain a single segment.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5332
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5333 The last slot is \member{bf_getcharbuffer}, of type
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5334 \ctype{getcharbufferproc}. This slot will only be present if the
17118 f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5335 \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5336 \member{tp_flags} field of the object's \ctype{PyTypeObject}. Before using
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5337 this slot, the caller should test whether it is present by using the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5338 \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5339 If present, it may be \NULL, indicating that the object's contents
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5340 cannot be used as \emph{8-bit characters}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5341 The slot function may also raise an error if the object's contents
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5342 cannot be interpreted as 8-bit characters. For example, if the object
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5343 is an array which is configured to hold floating point values, an
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5344 exception may be raised if a caller attempts to use
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5345 \member{bf_getcharbuffer} to fetch a sequence of 8-bit characters.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5346 This notion of exporting the internal buffers as ``text'' is used to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5347 distinguish between objects that are binary in nature, and those which
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5348 have character-based content.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5349
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5350 \strong{Note:} The current policy seems to state that these characters
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5351 may be multi-byte characters. This implies that a buffer size of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5352 \var{N} does not mean there are \var{N} characters present.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5353 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5354
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5355 \begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5356 Flag bit set in the type structure to indicate that the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5357 \member{bf_getcharbuffer} slot is known. This being set does not
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5358 indicate that the object supports the buffer interface or that the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5359 \member{bf_getcharbuffer} slot is non-\NULL.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5360 \end{datadesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5361
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5362 \begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5363 (PyObject self, int segment, void *ptrptr)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5364 Return a pointer to a readable segment of the buffer. This function
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5365 is allowed to raise an exception, in which case it must return
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5366 \code{-1}. The \var{segment} which is passed must be zero or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5367 positive, and strictly less than the number of segments returned by
17336 2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc. Greg Stein <gstein@lyra.org> parents: 17307 diff changeset	5368 the \member{bf_getsegcount} slot function. On success, it returns the
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc. Greg Stein <gstein@lyra.org> parents: 17307 diff changeset	5369 length of the buffer memory, and sets \code{*\var{ptrptr}} to a
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc. Greg Stein <gstein@lyra.org> parents: 17307 diff changeset	5370 pointer to that memory.
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5371 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5372
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5373 \begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5374 (PyObject self, int segment, void *ptrptr)}
17336 2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc. Greg Stein <gstein@lyra.org> parents: 17307 diff changeset	5375 Return a pointer to a writable memory buffer in \code{*\var{ptrptr}},
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc. Greg Stein <gstein@lyra.org> parents: 17307 diff changeset	5376 and the length of that segment as the function return value.
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc. Greg Stein <gstein@lyra.org> parents: 17307 diff changeset	5377 The memory buffer must correspond to buffer segment \var{segment}.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	5378 Must return \code{-1} and set an exception on error.
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	5379 \exception{TypeError} should be raised if the object only supports
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	5380 read-only buffers, and \exception{SystemError} should be raised when
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	5381 \var{segment} specifies a segment that doesn't exist.
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	5382 % Why doesn't it raise ValueError for this one?
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5383 % GJS: because you shouldn't be calling it with an invalid
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5384 % segment. That indicates a blatant programming error in the C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5385 % code.
11176 64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	5386 \end{ctypedesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary. Fred Drake <fdrake@acm.org> parents: 11168 diff changeset	5387
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5388 \begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5389 (PyObject self, int lenp)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5390 Return the number of memory segments which comprise the buffer. If
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5391 \var{lenp} is not \NULL, the implementation must report the sum of the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5392 sizes (in bytes) of all segments in \code{*\var{lenp}}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5393 The function cannot fail.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5394 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5395
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5396 \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5397 (PyObject self, int segment, const char *ptrptr)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5398 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5399
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5400
18944 a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	5401 \section{Supporting the Iterator Protocol
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	5402 \label{supporting-iteration}}
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	5403
a0819708fe9c Move away from apply() to using extended call syntax for some example Fred Drake <fdrake@acm.org> parents: 18785 diff changeset	5404
17118 f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5405 \section{Supporting Cyclic Garbarge Collection
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5406 \label{supporting-cycle-detection}}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5407
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5408 Python's support for detecting and collecting garbage which involves
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5409 circular references requires support from object types which are
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5410 ``containers'' for other objects which may also be containers. Types
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5411 which do not store references to other objects, or which only store
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5412 references to atomic types (such as numbers or strings), do not need
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5413 to provide any explicit support for garbage collection.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5414
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5415 To create a container type, the \member{tp_flags} field of the type
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5416 object must include the \constant{Py_TPFLAGS_GC} and provide an
17147 349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5417 implementation of the \member{tp_traverse} handler. The computed
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5418 value of the \member{tp_basicsize} field must include
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5419 \constant{PyGC_HEAD_SIZE} as well. If instances of the type are
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5420 mutable, a \member{tp_clear} implementation must also be provided.
17118 f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5421
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5422 \begin{datadesc}{Py_TPFLAGS_GC}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5423 Objects with a type with this flag set must conform with the rules
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5424 documented here. For convenience these objects will be referred to
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5425 as container objects.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5426 \end{datadesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5427
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5428 \begin{datadesc}{PyGC_HEAD_SIZE}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5429 Extra memory needed for the garbage collector. Container objects
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5430 must include this in the calculation of their tp_basicsize. If the
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5431 collector is disabled at compile time then this is \code{0}.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5432 \end{datadesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5433
17147 349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5434 Constructors for container types must conform to two rules:
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5435
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5436 \begin{enumerate}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5437 \item The memory for the object must be allocated using
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5438 \cfunction{PyObject_New()} or \cfunction{PyObject_VarNew()}.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5439
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5440 \item Once all the fields which may contain references to other
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5441 containers are initialized, it must call
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5442 \cfunction{PyObject_GC_Init()}.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5443 \end{enumerate}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5444
17118 f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5445 \begin{cfuncdesc}{void}{PyObject_GC_Init}{PyObject *op}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5446 Adds the object \var{op} to the set of container objects tracked by
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5447 the collector. The collector can run at unexpected times so objects
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5448 must be valid while being tracked. This should be called once all
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5449 the fields followed by the \member{tp_traverse} handler become valid,
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5450 usually near the end of the constructor.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5451 \end{cfuncdesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5452
17147 349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5453 Similarly, the deallocator for the object must conform to a similar
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5454 pair of rules:
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5455
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5456 \begin{enumerate}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5457 \item Before fields which refer to other containers are invalidated,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5458 \cfunction{PyObject_GC_Fini()} must be called.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5459
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5460 \item The object's memory must be deallocated using
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5461 \cfunction{PyObject_Del()}.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5462 \end{enumerate}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5463
17118 f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5464 \begin{cfuncdesc}{void}{PyObject_GC_Fini}{PyObject *op}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5465 Remove the object \var{op} from the set of container objects tracked
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5466 by the collector. Note that \cfunction{PyObject_GC_Init()} can be
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5467 called again on this object to add it back to the set of tracked
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5468 objects. The deallocator (\member{tp_dealloc} handler) should call
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5469 this for the object before any of the fields used by the
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5470 \member{tp_traverse} handler become invalid.
17209 52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini(). Fred Drake <fdrake@acm.org> parents: 17147 diff changeset	5471
52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini(). Fred Drake <fdrake@acm.org> parents: 17147 diff changeset	5472 \strong{Note:} Any container which may be referenced from another
52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini(). Fred Drake <fdrake@acm.org> parents: 17147 diff changeset	5473 object reachable by the collector must itself be tracked by the
52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini(). Fred Drake <fdrake@acm.org> parents: 17147 diff changeset	5474 collector, so it is generally not safe to call this function
52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini(). Fred Drake <fdrake@acm.org> parents: 17147 diff changeset	5475 anywhere but in the object's deallocator.
17118 f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5476 \end{cfuncdesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5477
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5478 The \member{tp_traverse} handler accepts a function parameter of this
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5479 type:
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5480
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5481 \begin{ctypedesc}[visitproc]{int (visitproc)(PyObject object, void *arg)}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5482 Type of the visitor function passed to the \member{tp_traverse}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5483 handler. The function should be called with an object to traverse
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5484 as \var{object} and the third parameter to the \member{tp_traverse}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5485 handler as \var{arg}.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5486 \end{ctypedesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5487
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5488 The \member{tp_traverse} handler must have the following type:
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5489
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5490 \begin{ctypedesc}[traverseproc]{int (traverseproc)(PyObject self,
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5491 visitproc visit, void *arg)}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5492 Traversal function for a container object. Implementations must
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5493 call the \var{visit} function for each object directly contained by
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5494 \var{self}, with the parameters to \var{visit} being the contained
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5495 object and the \var{arg} value passed to the handler. If
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5496 \var{visit} returns a non-zero value then an error has occurred and
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5497 that value should be returned immediately.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5498 \end{ctypedesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5499
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5500 The \member{tp_clear} handler must be of the \ctype{inquiry} type, or
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5501 \NULL{} if the object is immutable.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5502
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5503 \begin{ctypedesc}[inquiry]{int (inquiry)(PyObject self)}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5504 Drop references that may have created reference cycles. Immutable
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5505 objects do not have to define this method since they can never
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5506 directly create reference cycles. Note that the object must still
18447 ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(), Fred Drake <fdrake@acm.org> parents: 18438 diff changeset	5507 be valid after calling this method (don't just call
17118 f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5508 \cfunction{Py_DECREF()} on a reference). The collector will call
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5509 this method if it detects that this object is involved in a
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5510 reference cycle.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5511 \end{ctypedesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5512
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about Fred Drake <fdrake@acm.org> parents: 17057 diff changeset	5513
17147 349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5514 \subsection{Example Cycle Collector Support
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5515 \label{example-cycle-support}}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5516
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5517 This example shows only enough of the implementation of an extension
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5518 type to show how the garbage collector support needs to be added. It
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5519 shows the definition of the object structure, the
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5520 \member{tp_traverse}, \member{tp_clear} and \member{tp_dealloc}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5521 implementations, the type structure, and a constructor --- the module
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5522 initialization needed to export the constructor to Python is not shown
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5523 as there are no special considerations there for the collector. To
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5524 make this interesting, assume that the module exposes ways for the
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5525 \member{container} field of the object to be modified. Note that
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5526 since no checks are made on the type of the object used to initialize
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5527 \member{container}, we have to assume that it may be a container.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5528
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5529 \begin{verbatim}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5530 #include "Python.h"
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5531
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5532 typedef struct {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5533 PyObject_HEAD
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5534 PyObject *container;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5535 } MyObject;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5536
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5537 static int
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5538 my_traverse(MyObject self, visitproc visit, void arg)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5539 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5540 if (self->container != NULL)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5541 return visit(self->container, arg);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5542 else
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5543 return 0;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5544 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5545
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5546 static int
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5547 my_clear(MyObject *self)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5548 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5549 Py_XDECREF(self->container);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5550 self->container = NULL;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5551
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5552 return 0;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5553 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5554
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5555 static void
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5556 my_dealloc(MyObject *self)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5557 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5558 PyObject_GC_Fini((PyObject *) self);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5559 Py_XDECREF(self->container);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5560 PyObject_Del(self);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5561 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5562 \end{verbatim}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5563
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5564 \begin{verbatim}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5565 statichere PyTypeObject
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5566 MyObject_Type = {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5567 PyObject_HEAD_INIT(NULL)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5568 0,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5569 "MyObject",
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5570 sizeof(MyObject) + PyGC_HEAD_SIZE,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5571 0,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5572 (destructor)my_dealloc, /* tp_dealloc */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5573 0, /* tp_print */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5574 0, /* tp_getattr */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5575 0, /* tp_setattr */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5576 0, /* tp_compare */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5577 0, /* tp_repr */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5578 0, /* tp_as_number */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5579 0, /* tp_as_sequence */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5580 0, /* tp_as_mapping */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5581 0, /* tp_hash */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5582 0, /* tp_call */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5583 0, /* tp_str */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5584 0, /* tp_getattro */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5585 0, /* tp_setattro */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5586 0, /* tp_as_buffer */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5587 Py_TPFLAGS_DEFAULT \| Py_TPFLAGS_GC,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5588 0, /* tp_doc */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5589 (traverseproc)my_traverse, /* tp_traverse */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5590 (inquiry)my_clear, /* tp_clear */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5591 0, /* tp_richcompare */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5592 0, /* tp_weaklistoffset */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5593 };
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5594
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5595 /* This constructor should be made accessible from Python. */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5596 static PyObject *
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5597 new_object(PyObject unused, PyObject args)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5598 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5599 PyObject *container = NULL;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5600 MyObject *result = NULL;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5601
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5602 if (PyArg_ParseTuple(args, "\|O:new_object", &container)) {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5603 result = PyObject_New(MyObject, &MyObject_Type);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5604 if (result != NULL) {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5605 result->container = container;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5606 PyObject_GC_Init();
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5607 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5608 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5609 return (PyObject *) result;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5610 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5611 \end{verbatim}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5612
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an Fred Drake <fdrake@acm.org> parents: 17118 diff changeset	5613
12222 3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5614 % \chapter{Debugging \label{debugging}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5615 %
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release. Fred Drake <fdrake@acm.org> parents: 12200 diff changeset	5616 % XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
6991 f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	5617
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling. Guido van Rossum <guido@python.org> parents: 6653 diff changeset	5618
14736 2b9a890162b0 Include the new text on reporting bugs in a few useful places. Fred Drake <fdrake@acm.org> parents: 14696 diff changeset	5619 \appendix
2b9a890162b0 Include the new text on reporting bugs in a few useful places. Fred Drake <fdrake@acm.org> parents: 14696 diff changeset	5620 \chapter{Reporting Bugs}
2b9a890162b0 Include the new text on reporting bugs in a few useful places. Fred Drake <fdrake@acm.org> parents: 14696 diff changeset	5621 \input{reportingbugs}
2b9a890162b0 Include the new text on reporting bugs in a few useful places. Fred Drake <fdrake@acm.org> parents: 14696 diff changeset	5622
18192 19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	5623 \chapter{History and License}
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	5624 \input{license}
19bc63a84439 Move license information to a less annoying location in the document. Fred Drake <fdrake@acm.org> parents: 18020 diff changeset	5625
15953 8349b4dfc51a Undoing the whitespace patches which sneaked into the earlier patch. Marc-André Lemburg <mal@egenix.com> parents: 15952 diff changeset	5626 \input{api.ind} % Index -- must be last
5536 c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	5627
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual. Guido van Rossum <guido@python.org> parents: diff changeset	5628 \end{document}

Mercurial > cpython-lru_cache-weakref

annotate Doc/api/api.tex @ 19283:b865cd5c1925 legacy-trunk