Mercurial > cpython-lru_cache-weakref

annotate Doc/api/api.tex @ 14519:7435331b48ee legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
author Fred Drake <fdrake@acm.org>
date Tue, 12 Sep 2000 15:22:05 +0000
parents 2de1fb5302ed
children ff4ae691be9b
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 \makeindex % tell \index to actually write the .idx file
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
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
58 embedding Python is less straightforward that 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:
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
77 \code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
78 \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
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
105 \samp{\#include <python1.5/Python.h>}; this will break on
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
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
110
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
111 \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
112
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
113 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
114 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
115 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
116 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
117 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
118 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
119 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
120 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
121 \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
122 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
123 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
124 \ctype{PyTypeObject} objects.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
125
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
126 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
127 \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
128 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
129 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
130 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
131 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
132 \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
133 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
134
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
135
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
136 \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
137
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
138 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
139 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
140 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
141 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
142 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
143 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
144 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
145 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
146 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
147 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
148 ``don't do that.'')
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
149
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
150 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
151 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
152 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
153 \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
154 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
155 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
156 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
157 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
158 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
159 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
160 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
161 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
162 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
163 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
164 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
165 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
166
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
167 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
168 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
169 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
170 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
171 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
172 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
173 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
174 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
175 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
176 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
177 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
178 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
179 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
180 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
181
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
182 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
183 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
184 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
185 list, decrementing its reference count and possible deallocating it.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
186 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
187 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
188 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
189 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
190
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
191 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
192 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
193 \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
194 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
195 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
196 \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
197 becomes second nature.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
198
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
199
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
200 \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
201
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
202 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
203 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
204 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
205 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
206 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
207 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
208 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
209 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
210 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
211 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
212
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
213 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
214 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
215 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
216 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
217 \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
218 \cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
219 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
220 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
221 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
222 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
223 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
224 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
225
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
226 \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
227 PyObject *t;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
228
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
229 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
230 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
231 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
232 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
233 \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
234
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
235 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
236 set tuple items; \cfunction{PySequence_SetItem()} and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
237 \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
238 immutable data type. You should only use
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
239 \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
240 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
241
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
242 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
243 \cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
244 can also use \cfunction{PySequence_SetItem()}; this illustrates the
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
245 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
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 \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
248 PyObject *l, *x;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
249
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
250 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
251 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
252 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
253 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
254 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
255 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
256 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
257 \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
258
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
259 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
260 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
261 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
262 \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
263 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
264 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
265 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
266
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
267 \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
268 PyObject *t, *l;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
269
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
270 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
271 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
272 \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
273
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
274 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
275 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
276 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
277 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
278 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
279 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
280 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
281 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
282
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
283 \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
284 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
285 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
286 int i, n;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
287
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
288 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
289 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
290 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
291 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
292 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
293 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
294 }
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 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
296 }
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 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
298 \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
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 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
301 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
302 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
303 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
304 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
305 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
306 object. Therefore, the generic functions that return object
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
307 references, like \cfunction{PyObject_GetItem()} and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
308 \cfunction{PySequence_GetItem()}, always return a new reference (i.e.,
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
309 the 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
310
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
311 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
312 by a function depends on which function you call only --- \emph{the
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
313 plumage} (i.e., the type of the type of the object passed as an
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
314 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
315 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
316 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
317 same list using \cfunction{PySequence_GetItem()} (which happens to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
318 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
319 returned object.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
320
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
321 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
322 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
323 \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
324 \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
325
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
326 \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
327 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
328 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
329 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
330 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
331 PyObject *item;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
332
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
333 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
334 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
335 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
336 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
337 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
338 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
339 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
340 }
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 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
342 }
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 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
344 \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
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 \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
347 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
348 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
349 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
350 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
351 PyObject *item;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
352 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
353 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
354 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
355 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
356 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
357 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
358 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
359 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
360 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
361 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
362 }
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 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
364 }
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 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
366 \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
367
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
368
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
369 \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
370
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
371 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
372 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
373 \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
374 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
375 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
376 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
377 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
378
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
379
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
380 \section{Exceptions \label{exceptions}}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
381
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
382 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
383 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
384 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
385 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
386 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
387
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
388 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
389 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
390 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
391 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
392 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
393 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
394 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
395 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
396 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
397 \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
398
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 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
400 equivalent to using global storage in an unthreaded application). A
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
401 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
402 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
403 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
404 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
405 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
406 \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
407 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
408 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
409 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
410
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
411 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
412 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
413 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
414 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
415 \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
416 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
417 \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
418 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
419 \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
420 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
421 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
422 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
423 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
424
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
425 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
426 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
427 \withsubitem{(in module sys)}{\ttindex{exc_info()}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
428 \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
429 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
430 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
431 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
432 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
433 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
434 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
435 unwanted lifetime extension for objects that are referenced by the
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
436 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
437
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 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
439 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
440 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
441 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
442 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
443 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
444 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
445
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
446 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
447 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
448 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
449 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
450 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
451 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
452
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
453 \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
454 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
455 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
456 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
457 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
458 item = 0
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 return 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
460 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
461 \ttindex{incr_item()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
462
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
463 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
464
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 \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
466 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
467 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
468 /* 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
469 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
470 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
471
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
472 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
473 if (item == NULL) {
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
474 /* Handle KeyError only: */
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
475 if (!PyErr_ExceptionMatches(PyExc_KeyError)) 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
476
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
477 /* 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
478 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
479 item = PyInt_FromLong(0L);
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
480 if (item == NULL) goto 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
481 }
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 const_one = 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
484 if (const_one == NULL) goto 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
485
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
486 incremented_item = PyNumber_Add(item, 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
487 if (incremented_item == NULL) goto 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
488
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
489 if (PyObject_SetItem(dict, key, incremented_item) < 0) 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
490 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
491 /* 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
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 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
494 /* 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
495
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
496 /* 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
497 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
498 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
499 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
500
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 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
502 }
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 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
504 \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
505
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
506 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
507 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
508 \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
509 \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
510 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
511 \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
512 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
513 \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
514 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
515 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
516 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
517 \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
518 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
519
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
520
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
521 \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
522
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
523 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
524 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
525 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
526 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
527 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
528
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
529 The basic initialization function is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
530 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
531 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
532 fundamental modules \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
533 \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
534 \module{sys}\refbimodindex{sys}. It also initializes the module
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
535 search path (\code{sys.path}).%
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
536 \indexiii{module}{search}{path}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
537 \withsubitem{(in module sys)}{\ttindex{path}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
538
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
539 \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
540 (\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
541 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
542 \code{PySys_SetArgv(\var{argc},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
543 \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
544 \cfunction{Py_Initialize()}.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
545
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
546 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
547 details are slightly different),
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
548 \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
549 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
550 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
551 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
552 particular, it looks for a directory named
7923
23cc6ac5eba6 Don't assume that \version expands to the 3-character major.minor number; it
Fred Drake <fdrake@acm.org>
parents: 7807
diff changeset
553 \file{lib/python1.5} (replacing \file{1.5} with the current
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
554 interpreter version) relative to the parent directory where the
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
555 executable named \file{python} is found on the shell command search
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
556 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
557
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
558 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
559 \file{/usr/local/bin/python}, it will assume that the libraries are in
7923
23cc6ac5eba6 Don't assume that \version expands to the 3-character major.minor number; it
Fred Drake <fdrake@acm.org>
parents: 7807
diff changeset
560 \file{/usr/local/lib/python1.5}. (In fact, this particular path
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
561 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
562 \file{python} is found along \envvar{PATH}.) The user can override
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
563 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
564 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
565 setting \envvar{PYTHONPATH}.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
566
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
567 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
568 \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
569 \cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
570 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
571 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
572 provide its own implementation of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
573 \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
574 \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
575 \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
576 \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
577 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
578
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
579 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
580 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
581 \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
582 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
583 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
584 \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
585 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
586 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
587
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
588
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
589 \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
590
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
591 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
592 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
593 more detailed way with the interpreter.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
594
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
595 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
596 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
597 \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
598 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
599
13959
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
600 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
601 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
602 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
603 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
604 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
605 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
606 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
607 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
608
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
609 \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
610 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
611 (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
612 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
613 result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
614 \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
615 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
616
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
617 \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
618 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
619 \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
620 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
621 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
622 get the exception information.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
623 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
624
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
625 \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
626 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
627 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
628 \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
629 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
630
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
631 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
632 Read and execute a single statement from a file associated with an
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
633 interactive device. If \var{filename} is \NULL, \code{"???"} is
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
634 used instead. The user will be prompted using \code{sys.ps1} and
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
635 \code{sys.ps2}. Returns \code{0} when the input was executed
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
636 successfully, \code{-1} if there was an exception, or an error code
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
637 from the \file{errcode.h} include file distributed as part of Python
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
638 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
639 included by \file{Python.h}, so must be included specifically if
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
640 needed.)
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
641 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
642
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
643 \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
644 Read and execute statements from a file associated with an
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
645 interactive device until \EOF{} is reached. If \var{filename} is
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
646 \NULL, \code{"???"} is used instead. The user will be prompted
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
647 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
648 \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
649
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
650 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
651 int start}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
652 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
653 \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
654 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
655 must be evaluated many times.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
656 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
657
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
658 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
659 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
660 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
661 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
662 \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
663 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
664
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
665 \begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
666 PyObject *globals,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
667 PyObject *locals}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
668 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
669 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
670 \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
671 the source code.
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
672
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
673 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
674 \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
675 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
676
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
677 \begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
678 int start, PyObject *globals,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
679 PyObject *locals}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
680 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
681 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
682 \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
683 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
684
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
685 \begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
686 int start}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
687 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
688 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
689 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
690 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
691 \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
692 \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
693 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
694 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
695 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
696
11222
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
697 \begin{cvardesc}{int}{Py_eval_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
698 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
699 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
700 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
701
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
702 \begin{cvardesc}{int}{Py_file_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
703 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
704 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
705 \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
706 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
707 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
708
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
709 \begin{cvardesc}{int}{Py_single_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
710 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
711 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
712 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
713 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
714
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
715
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
716 \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
717
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
718 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
719 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
720
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
721 \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
722 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
723 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
724 \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
725 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
726
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
727 \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
728 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
729 \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
730 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
731
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
732 \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
733 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
734 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
735 \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
736 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
737 invoked.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
738
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
739 \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
740 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
741 \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
742 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
743 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
744 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
745 \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
746 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
747 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
748 \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
749 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
750
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
751 \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
752 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
753 \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
754 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
755 applies.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
756 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
757
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
758 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
759 interpreter core: \cfunction{_Py_Dealloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
760 \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
761 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
762
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
763
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
764 \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
765
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
766 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
767 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
768 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
769 \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
770 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
771 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
772 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
773 \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
774 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
775 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
776 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
777 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
778 already set it.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
779
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
780 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
781 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
782 \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
783 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
784 \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
785 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
786 for each thread.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
787
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
788 % 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
789 % 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
790
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
791 \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
792 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
793 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
794 (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
795 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
796
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
797 \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
798 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
799 \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
800 \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
801 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
802 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
803 \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
804 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
805 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
806 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
807 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
808 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
809
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
810 \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
811 Equivalent to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
812 \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
813 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
814 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
815 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
816
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
817 \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
818 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
819 \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
820 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
821 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
822 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
823 occur.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
824 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
825
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
826 \begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
827 Under certain circumstances, the values returned by
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
828 \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
829 \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
830 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
831 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
832 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
833 performance.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
834 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
835
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
836 \begin{cfuncdesc}{void}{PyErr_Clear}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
837 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
838 is no effect.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
839 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
840
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
841 \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
842 PyObject **ptraceback}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
843 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
844 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
845 \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
846 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
847 \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
848 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
849 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
850 temporarily.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
851 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
852
14279
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
853 \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value,
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
854 PyObject *traceback}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
855 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
856 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
857 \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
858 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
859 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
860 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
861 (Violating these rules will cause subtle problems later.) This call
14279
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
862 takes away a reference to each object, i.e.\ 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
863 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
864 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
865 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
866 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
867 temporarily.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
868 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
869
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
870 \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
871 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
872 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
873 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
874 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
875 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
876 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
877
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
878 \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
879 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
880 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
881 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
882 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
883
12355
04802b7e8a1f Yet another markup nit: functions that are part of the Python/C API
Fred Drake <fdrake@acm.org>
parents: 12354
diff changeset
884 \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
885 const char *format, \moreargs}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
886 This function sets the error indicator.
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
887 \var{exception} should be a Python object.
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
888 \var{fmt} should be a string, containing format codes, similar to
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
889 \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
890 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
891
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
892 \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
893 \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
894 \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
895 \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
896 \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
897 \end{tableii}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
898
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
899 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
900 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
901 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
902
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
903 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
904 \end{cfuncdesc}
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
905
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
906 \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
907 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
908 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
909
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
910 \begin{cfuncdesc}{int}{PyErr_BadArgument}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
911 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
912 \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
913 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
914 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
915
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
916 \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
917 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
918 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
919 \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
920 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
921
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
922 \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
923 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
924 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
925 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
926 \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
927 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
928 then calls
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
929 \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
930 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
931 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
932 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
933 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
934 \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
935 error.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
936 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
937
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
938 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
939 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
940 \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
941 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
942 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
943 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
944
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
945 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
946 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
947 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
948 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
949 \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
950 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
951 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
952 \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
953 \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
954 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
955 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
956 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
957 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
958
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
959 \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
960 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
961 \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
962 \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
963 \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
964 \exception{KeyboardInterrupt} will be raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
965 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
966 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
967
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
968 \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
969 PyObject *base,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
970 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
971 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
972 \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
973 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
974 \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
975 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
976 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
977 \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
978 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
979 \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
980 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
981 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
982 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
983 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
984
14330
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
985 \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
986 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
987 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
988 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
989 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
990
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
991 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
992 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
993 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
994 message.
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
995 \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
996
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
997 \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
998
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
999 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
1000 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
1001 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
1002 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
1003
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1004 \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
1005 \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
1006 \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
1007 \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
1008 \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
1009 \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1010 \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1011 \lineiii{PyExc_EOFError}{\exception{EOFError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1012 \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
1013 \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1014 \lineiii{PyExc_IOError}{\exception{IOError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1015 \lineiii{PyExc_ImportError}{\exception{ImportError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1016 \lineiii{PyExc_IndexError}{\exception{IndexError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1017 \lineiii{PyExc_KeyError}{\exception{KeyError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1018 \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1019 \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1020 \lineiii{PyExc_NameError}{\exception{NameError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1021 \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1022 \lineiii{PyExc_OSError}{\exception{OSError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1023 \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1024 \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1025 \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1026 \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1027 \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1028 \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1029 \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1030 \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
1031 \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1032 \end{tableiii}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1033
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1034 \noindent
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1035 Notes:
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1036 \begin{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1037 \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
1038 This is a base class for other standard exceptions.
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1039
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1040 \item[(2)]
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1041 Only defined on Windows; protect code that uses this by testing that
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1042 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
1043 \end{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1044
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1045
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1046 \section{Deprecation of String Exceptions}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1047
13150
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1048 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
1049 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
1050 \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
1051
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1052 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
1053 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
1054 release.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1055
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1056
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1057 \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
1058
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1059 The functions in this chapter perform various utility tasks, such as
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1060 parsing function arguments and constructing Python values from C
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1061 values.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1062
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1063 \section{OS 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
1064
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1065 \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
1066 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
1067 \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
1068 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
1069 \cdata{Py_InteractiveFlag} is true, this function also returns true if
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1070 the \var{name} 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
1071 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
1072 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1073
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1074 \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1075 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
1076 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
1077 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
1078 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1079
13053
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1080 \begin{cfuncdesc}{void}{PyOS_AfterFork}{}
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1081 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
1082 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
1083 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
1084 process, this function does not need to be called.
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1085 \end{cfuncdesc}
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1086
14279
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1087 \begin{cfuncdesc}{int}{PyOS_CheckStack}{}
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1088 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
1089 reliable check, but is only available when \code{USE_STACKCHECK} is
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1090 defined (currently on Windows using the Microsoft Visual C++ compiler
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1091 and on the Macintosh). \code{USE_CHECKSTACK} will be defined
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1092 automatically; you should never change the definition in your own
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1093 code.
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1094 \end{cfuncdesc}
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1095
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1096
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1097 \section{Process Control \label{processControl}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1098
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1099 \begin{cfuncdesc}{void}{Py_FatalError}{char *message}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1100 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
1101 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
1102 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
1103 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
1104 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
1105 \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
1106 produce a \file{core} file.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1107 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1108
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1109 \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
1110 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
1111 \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
1112 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
1113 \code{exit(\var{status})}\ttindex{exit()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1114 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1115
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1116 \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
1117 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
1118 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1119 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
1120 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
1121 functions can be registered.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1122 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
1123 \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
1124 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
1125 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
1126 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
1127 by \var{func}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1128 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1129
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1130
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1131 \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
1132
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1133 \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
1134 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
1135 \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
1136 \var{globals} and \var{locals} arguments set to \NULL{}. When the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1137 \var{name} argument contains a dot (i.e., when it specifies a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1138 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
1139 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
1140 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
1141 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
1142 \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
1143 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
1144 \index{package variable!\code{__all__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1145 \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
1146 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
1147 \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
1148 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
1149 \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
1150 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1151
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1152 \begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, 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
1153 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
1154 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
1155 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
1156 directly.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1157
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1158 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
1159 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
1160 (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
1161 \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
1162 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
1163 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
1164 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1165
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1166 \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
1167 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
1168 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
1169 \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
1170 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
1171 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
1172 \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
1173 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1174
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1175 \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
1176 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
1177 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
1178 \function{reload()} function calls this function directly. Return a
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1179 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
1180 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
1181 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1182
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1183 \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
1184 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
1185 \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
1186 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
1187 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
1188 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
1189 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
1190 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
1191 import a module.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1192 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
1193 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1194
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1195 \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
1196 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
1197 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
1198 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
1199 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
1200 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
1201 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
1202 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
1203 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1204
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1205 \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
1206 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
1207 \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
1208 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
1209 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
1210 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1211
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1212 \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
1213 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
1214 (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
1215 variable.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1216 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1217
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1218 \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
1219 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
1220 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1221
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1222 \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
1223 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
1224 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1225
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1226 \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
1227 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
1228 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1229
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1230 \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
1231 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
1232 \end{cfuncdesc}
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
1233
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1234 \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
1235 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
1236 \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
1237
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
1238 \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
1239 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
1240 \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
1241 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
1242 successful load, use \cfunction{PyImport_ImportModule()}.
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1243 (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
1244 already imported.)
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1245 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1246
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1247 \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
1248 This is the structure type definition for frozen module descriptors,
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1249 as generated by the \program{freeze}\index{freeze utility} utility
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1250 (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
1251 definition, found in \file{Include/import.h}, is:
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1252
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1253 \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
1254 struct _frozen {
6480
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1255 char *name;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1256 unsigned char *code;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1257 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
1258 };
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1259 \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
1260 \end{ctypedesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1261
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1262 \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
1263 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
1264 _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
1265 \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
1266 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
1267 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
1268 \end{cvardesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1269
14337
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1270 \begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1271 void (*initfunc)(void)}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1272 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
1273 is a convenience wrapper around \cfunction{PyImport_ExtendInittab()},
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1274 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
1275 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
1276 \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
1277 attempted import. This should be called before
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1278 \cfunction{Py_Initialize()}.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1279 \end{cfuncdesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1280
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1281 \begin{ctypedesc}[_inittab]{struct _inittab}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1282 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
1283 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
1284 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
1285 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
1286 \cfunction{PyImport_ExtendInittab()} to provide additional built-in
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1287 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
1288
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1289 \begin{verbatim}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1290 struct _inittab {
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1291 char *name;
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1292 void (*initfunc)(void);
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1293 };
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1294 \end{verbatim}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1295 \end{ctypedesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1296
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1297 \begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1298 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
1299 \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
1300 \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
1301 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
1302 \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
1303 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
1304 internal table. This should be called before
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1305 \cfunction{Py_Initialize()}.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1306 \end{cfuncdesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1307
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1308
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1309 \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
1310
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1311 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
1312 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
1313 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
1314 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
1315
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1316 \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
1317
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1318 \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
1319 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
1320 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
1321 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
1322 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
1323 \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
1324 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1325
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1326 \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
1327 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
1328 \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
1329 \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
1330 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
1331 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1332
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1333 \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
1334 char *attr_name}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1335 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
1336 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
1337 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1338 \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
1339 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1340
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1341
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1342 \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
1343 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
1344 \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
1345 \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
1346 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
1347 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1348
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1349
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1350 \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
1351 PyObject *attr_name}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1352 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
1353 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
1354 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1355 \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
1356 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1357
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1358
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1359 \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1360 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
1361 \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
1362 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
1363 \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
1364 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1365
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1366
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1367 \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1368 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
1369 object \var{o},
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1370 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
1371 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
1372 \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
1373 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1374
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1375
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1376 \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
1377 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
1378 \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
1379 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
1380 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1381
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1382
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1383 \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
1384 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
1385 \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
1386 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
1387 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1388
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1389
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1390 \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
1391 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
1392 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
1393 \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
1394 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
1395 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
1396 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1397
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1398
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1399 \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
1400 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
1401 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
1402 \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
1403 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
1404 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
1405 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
1406 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1407
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1408
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1409 \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
1410 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
1411 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
1412 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
1413 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
1414 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
1415 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1416
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1417
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1418 \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
1419 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
1420 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
1421 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
1422 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
1423 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
1424 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1425
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1426
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1427 \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
1428 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
1429 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
1430 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
1431 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1432
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1433
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1434 \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
1435 PyObject *args}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1436 Call a callable Python object \var{callable_object}, with
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1437 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
1438 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
1439 call on success, or \NULL{} on failure. This is the equivalent
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1440 of the Python expression \samp{apply(\var{o}, \var{args})}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1441 \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
1442 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1443
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1444 \begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1445 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
1446 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
1447 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
1448 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
1449 result of the call on success, or \NULL{} on failure. This is
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1450 the equivalent of the Python expression \samp{apply(\var{o},
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1451 \var{args})}.\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
1452 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1453
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1454
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1455 \begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1456 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
1457 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
1458 \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
1459 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
1460 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
1461 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
1462 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
1463 \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
1464 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
1465 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1466
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1467
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1468 \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1469 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
1470 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
1471 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
1472 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1473
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1474
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1475 \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1476 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
1477 \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
1478 \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
1479 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
1480 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1481
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1482
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1483 \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
1484 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
1485 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
1486 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
1487 \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
1488 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1489
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1490 \begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1491 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
1492 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
1493 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
1494 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
1495 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1496
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1497
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1498 \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
1499 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
1500 \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
1501 \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
1502 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1503
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1504
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1505 \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1506 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
1507 Returns \code{-1} on failure. This is the equivalent
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1508 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
1509 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1510
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1511
9931
00fc18ac6aeb Header for PyObject_DelItem() mentioned non-existing 3rd argument.
Guido van Rossum <guido@python.org>
parents: 9476
diff changeset
1512 \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
1513 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
1514 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
1515 \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
1516 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1517
13592
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1518 \begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o}
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1519 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
1520 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
1521 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
1522 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
1523 descriptor value. Returns \code{-1} on failure.
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1524 \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
1525
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1526 \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
1527
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1528 \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1529 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
1530 false otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1531 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
1532 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1533
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1534
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1535 \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
1536 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
1537 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1538 \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
1539 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1540
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1541
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1542 \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
1543 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
1544 \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
1545 \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
1546 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1547
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1548
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1549 \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
1550 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
1551 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1552 \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
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*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1557 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
1558 failure.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1559 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
1560 \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
1561 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1562
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 \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
1565 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
1566 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
1567 \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
1568 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1569
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1570
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1571 \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
1572 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
1573 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
1574 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
1575 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1576
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1577
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1578 \begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, 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
1579 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
1580 \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
1581 \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
1582 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
1583 (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
1584 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1585
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1586
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1587 \begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1588 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
1589 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
1590 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1591
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1592
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1593 \begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1594 Returns \var{o} on success, or \NULL{} on failure.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1595 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
1596 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1597
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1598
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1599 \begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1600 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
1601 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
1602 \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
1603 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1604
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1605
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1606 \begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1607 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
1608 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1609 \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
1610 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1611
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1612
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1613 \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
1614 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
1615 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
1616 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
1617 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1618
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1619
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1620 \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
1621 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
1622 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
1623 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
1624 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1625
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1626
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1627 \begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1628 Returns the result of ``anding'' \var{o2} and \var{o2} on success and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1629 \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
1630 expression \samp{\var{o1} and \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
1631 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1632
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1633
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1634 \begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1635 Returns the bitwise exclusive or of \var{o1} by \var{o2} on success,
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1636 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
1637 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
1638 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1639
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1640 \begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1641 Returns the result of \var{o1} and \var{o2} on success, or \NULL{} on
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1642 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1643 \samp{\var{o1} or \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
1644 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1645
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1646 \begin{cfuncdesc}{PyObject*}{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
1647 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
1648 \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
1649 \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
1650 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
1651 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
1652 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
1653 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
1654 \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
1655 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
1656 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
1657 \bifuncindex{coerce}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1658 \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
1659
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1660 \begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1661 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
1662 \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
1663 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
1664 \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
1665
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1666 \begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1667 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
1668 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
1669 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
1670 \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
1671
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1672 \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
1673 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
1674 \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
1675 \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
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
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1679 \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
1680
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1681 \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
1682 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
1683 \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
1684 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1685
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1686 \begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1687 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
1688 \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
1689 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
1690 \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
1691 \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
1692
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1693 \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
1694 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
1695 failure. This is the equivalent of the Python
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1696 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
1697 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1698
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 \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
1701 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
1702 \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
1703 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
1704 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1705
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1706
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1707 \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
1708 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
1709 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
1710 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1711
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1712
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1713 \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
1714 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
1715 \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
1716 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
1717 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1718
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1719
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1720 \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
1721 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
1722 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
1723 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
1724 \end{cfuncdesc}
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}{PySequence_DelItem}{PyObject *o, int i}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1727 Delete the \var{i}th element of object \var{v}. Returns
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1728 \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
1729 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
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
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1732 \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
1733 int i2, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1734 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
1735 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
1736 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
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 \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
1740 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
1741 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
1742 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
1743 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1744
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1745 \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1746 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
1747 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
1748 \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
1749 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1750
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1751 \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
1752 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
1753 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
1754 \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
1755 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
1756 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1757
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1758 \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
1759 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
1760 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
1761 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
1762 \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
1763 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1764
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1765 \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
1766 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
1767 \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
1768 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
1769 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1770
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
1771 \begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
1772 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
1773 \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
1774 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
1775
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
1776 \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
1777 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
1778 \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
1779 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
1780 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
1781
7493
6857acbe2e74 Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7467
diff changeset
1782
14519
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
1783 \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
1784 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
1785 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
1786 \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
1787 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
1788 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
1789 \end{cfuncdesc}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
1790
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
1791 \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
1792 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
1793 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
1794 bounds. The caller is expected to get the length of the sequence by
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
1795 calling \cfunction{PyObject_Size()} on \var{o}, since lists and tuples
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
1796 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
1797 \end{cfuncdesc}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
1798
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
1799
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1800 \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
1801
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1802 \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
1803 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
1804 \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
1805 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1806
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1807
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1808 \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
1809 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
1810 \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
1811 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
1812 \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
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}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1817 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
1818 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1819 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
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}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1824 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
1825 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1826 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
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}{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
1831 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
1832 \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
1833 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
1834 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
1835 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1838 \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
1839 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
1840 \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
1841 \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
1842 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
1843 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1844
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1845
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1846 \begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1847 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
1848 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
1849 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
1850 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1851
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1852
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1853 \begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1854 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
1855 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
1856 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
1857 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1858
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1859
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1860 \begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1861 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
1862 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
1863 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
1864 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
1865 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1866
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1867
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1868 \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
1869 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
1870 \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
1871 \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
1872 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1873
9383
2b34461ba4a3 PyMapping_SetItemString() returns int, not an object.
Guido van Rossum <guido@python.org>
parents: 8881
diff changeset
1874 \begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1875 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
1876 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
1877 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
1878 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1879
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1880
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1881 \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
1882
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1883 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
1884 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
1885 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
1886 that it has the right type, you must perform a type check first;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1887 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
1888 \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
1889 ``family tree'' of Python object types.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1890
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1891
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1892 \section{Fundamental Objects \label{fundamental}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1893
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1894 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
1895 \code{None}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1896
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1897
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1898 \subsection{Type Objects \label{typeObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1899
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1900 \obindex{type}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1901 \begin{ctypedesc}{PyTypeObject}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1902 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
1903 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1904
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1905 \begin{cvardesc}{PyObject*}{PyType_Type}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1906 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
1907 \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
1908 \withsubitem{(in module types)}{\ttindex{TypeType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1909 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1910
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1911 \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
1912 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
1913 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1914
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1915 \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
1916 Returns true if the type object \var{o} sets the feature
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1917 \var{feature}. Type features are denoted by single bit flags. The
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1918 only defined feature flag is \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1919 described in section \ref{buffer-structs}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1920 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1921
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1922
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1923 \subsection{The None Object \label{noneObject}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1924
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1925 \obindex{None@\texttt{None}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1926 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
1927 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
1928 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
1929 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
1930
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1931 \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
1932 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
1933 no methods.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1934 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1935
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1936
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1937 \section{Sequence Objects \label{sequenceObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1938
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1939 \obindex{sequence}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1940 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
1941 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
1942 objects that are intrinsic to the Python language.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1943
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1944
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1945 \subsection{String Objects \label{stringObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1946
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1947 \obindex{string}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1948 \begin{ctypedesc}{PyStringObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
1949 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
1950 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1951
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1952 \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
1953 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
1954 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
1955 layer.\withsubitem{(in module types)}{\ttindex{StringType}}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1956 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1957
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1958 \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
1959 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
1960 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1961
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1962 \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
1963 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
1964 \NULL{} on failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1965 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1966
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1967 \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
1968 int len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1969 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
1970 \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
1971 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
1972 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1973
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1974 \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
1975 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
1976 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1977
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1978 \begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1979 Macro form of \cfunction{PyString_GetSize()} but without error
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1980 checking.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1981 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1982
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1983 \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
1984 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
1985 \var{string}. The pointer refers to the internal buffer of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1986 \var{string}, not a copy. The data must not be modified in any way.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1987 It must not be de-allocated.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1988 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1989
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1990 \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
1991 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
1992 checking.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1993 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1994
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1995 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1996 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
1997 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
1998 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
1999 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
2000 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
2001 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
2002 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
2003 \NULL{}; the appropriate exception will be set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2004 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2005
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2006 \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2007 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
2008 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
2009 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
2010 the reference count of \var{newpart}.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2011 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2012
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2013 \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
2014 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
2015 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
2016 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
2017 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2018
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2019 \begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2020 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
2021 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
2022 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
2023 a tuple.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2024 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2025
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2026 \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
2027 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
2028 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
2029 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
2030 \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
2031 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
2032 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
2033 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
2034 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
2035 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
2036 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
2037 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2038
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2039 \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
2040 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
2041 \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
2042 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
2043 interned string object with the same value.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2044 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2045
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2046 \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
2047 int size,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2048 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2049 const char *errors}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2050 Create a string object by decoding \var{size} bytes of the encoded
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2051 buffer \var{s}. \var{encoding} and \var{errors} have the same meaning
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2052 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
2053 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
2054 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
2055 codec.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2056 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2057
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2058 \begin{cfuncdesc}{PyObject*}{PyString_Encode}{const Py_UNICODE *s,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2059 int size,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2060 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2061 const char *errors}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2062 Encodes the \ctype{Py_UNICODE} buffer of the given size and returns a
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2063 Python string object. \var{encoding} and \var{errors} have the same
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2064 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
2065 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
2066 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
2067 codec.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2068 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2069
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2070 \begin{cfuncdesc}{PyObject*}{PyString_AsEncodedString}{PyObject *unicode,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2071 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2072 const char *errors}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2073 Encodes a string object and returns the result as Python string
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2074 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
2075 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
2076 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
2077 \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
2078 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2079
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2080
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2081 \subsection{Unicode Objects \label{unicodeObjects}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2082 \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2083
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2084 %--- Unicode Type -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2085
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2086 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
2087 implementation in Python:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2088
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2089 \begin{ctypedesc}{Py_UNICODE}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2090 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
2091 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
2092 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
2093 \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
2094 native platform compatibility. On all other platforms,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2095 \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
2096 \end{ctypedesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2097
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2098 \begin{ctypedesc}{PyUnicodeObject}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2099 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
2100 \end{ctypedesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2101
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2102 \begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2103 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
2104 \end{cvardesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2105
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2106 %--- 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
2107
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2108 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
2109 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
2110
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2111 \begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2112 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
2113 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2114
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2115 \begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2116 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
2117 PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2118 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2119
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2120 \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
2121 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
2122 a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2123 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2124
12932
1fa7c119b7a5 Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support.
Fred Drake <fdrake@acm.org>
parents: 12930
diff changeset
2125 \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
2126 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
2127 has to be a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2128 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2129
12932
1fa7c119b7a5 Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support.
Fred Drake <fdrake@acm.org>
parents: 12930
diff changeset
2130 \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
2131 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
2132 o has to be a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2133 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2134
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2135 % --- Unicode character properties ---------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2136
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2137 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
2138 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
2139 functions depending on the Python configuration.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2140
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2141 \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
2142 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
2143 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2144
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2145 \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
2146 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
2147 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2148
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2149 \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
2150 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
2151 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2152
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2153 \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
2154 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
2155 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2156
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2157 \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
2158 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
2159 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2160
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2161 \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
2162 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
2163 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2164
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2165 \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
2166 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
2167 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2168
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2169 \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
2170 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
2171 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2172
13321
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2173 \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
2174 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
2175 \end{cfuncdesc}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2176
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2177 \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
2178 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
2179 \end{cfuncdesc}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2180
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2181 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
2182
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2183 \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
2184 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
2185 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2186
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2187 \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
2188 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
2189 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2190
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2191 \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
2192 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
2193 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2194
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2195 \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
2196 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
2197 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
2198 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2199
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2200 \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
2201 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
2202 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
2203 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2204
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2205 \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
2206 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
2207 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
2208 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2209
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2210 % --- Plain Py_UNICODE ---------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2211
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2212 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
2213 use these APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2214
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2215 \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
2216 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2217
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2218 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
2219 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
2220 undefined. It is the user's responsibility to fill in the needed data.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2221 The buffer is copied into the new object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2222 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2223
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2224 \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
2225 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
2226 \ctype{Py_UNICODE} buffer.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2227 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2228
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2229 \begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2230 Return the length of the Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2231 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2232
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2233 \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
2234 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2235 const char *errors}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2236
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2237 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
2238 reference with incremented refcount.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2239
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2240 Coercion is done in the following way:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2241 \begin{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2242 \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
2243 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
2244 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
2245
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2246 \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
2247 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
2248 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
2249 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
2250
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2251 \item All other objects cause an exception.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2252 \end{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2253 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
2254 for decref'ing the returned objects.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2255 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2256
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2257 \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
2258
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2259 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
2260 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
2261 Unicode is needed.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2262 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2263
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2264 % --- wchar_t support for platforms which support it ---------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2265
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2266 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
2267 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
2268 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
2269 \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
2270
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2271 \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
2272 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2273 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
2274 given size. Returns \NULL{} on failure.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2275 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2276
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2277 \begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2278 wchar_t *w,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2279 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2280 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
2281 \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
2282 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
2283 of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2284 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2285
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2286
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2287 \subsubsection{Builtin Codecs \label{builtinCodecs}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2288
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2289 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
2290 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
2291 following functions.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2292
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2293 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
2294 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
2295 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
2296
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2297 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
2298 is UTF-8.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2299
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2300 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
2301 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
2302 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
2303
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2304 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
2305 following generic ones are documented for simplicity.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2306
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2307 % --- Generic Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2308
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2309 These are the generic codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2310
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2311 \begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2312 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2313 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2314 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2315 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
2316 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
2317 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
2318 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
2319 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
2320 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2321 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2322
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2323 \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
2324 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2325 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2326 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2327 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
2328 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
2329 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
2330 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
2331 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
2332 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2333 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2334
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2335 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2336 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2337 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2338 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
2339 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
2340 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
2341 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
2342 \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
2343 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2344
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2345 % --- UTF-8 Codecs -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2346
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2347 These are the UTF-8 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2348
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2349 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2350 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2351 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2352 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
2353 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
2354 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2355 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2356
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2357 \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
2358 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2359 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2360 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
2361 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
2362 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2363 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2364
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2365 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2366 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
2367 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2368 \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
2369 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2370
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2371 % --- UTF-16 Codecs ------------------------------------------------------ */
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2372
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2373 These are the UTF-16 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2374
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2375 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2376 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2377 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2378 int *byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2379 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
2380 returns the corresponding Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2381
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2382 \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
2383 to ``strict''.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2384
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2385 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
2386 the given byte order:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2387
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2388 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2389 *byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2390 *byteorder == 0: native order
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2391 *byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2392 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2393
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2394 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
2395 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
2396 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
2397 order at the end of input data.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2398
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2399 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
2400
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2401 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
2402 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2403
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2404 \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
2405 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2406 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2407 int byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2408 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
2409 Unicode data in \var{s}.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2410
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2411 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
2412 following byte order:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2413
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2414 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2415 byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2416 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
2417 byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2418 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2419
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2420 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
2421 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
2422 prepended.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2423
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2424 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
2425 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
2426 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
2427
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2428 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
2429 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2430
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2431 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2432 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
2433 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
2434 ``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
2435 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2436 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2437
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2438 % --- Unicode-Escape Codecs ----------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2439
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2440 These are the ``Unicode Esacpe'' codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2441
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2442 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2443 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2444 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2445 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
2446 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
2447 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2448 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2449
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2450 \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
2451 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2452 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2453 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
2454 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
2455 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2456 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2457
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2458 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2459 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
2460 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
2461 \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
2462 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2463
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2464 % --- Raw-Unicode-Escape Codecs ------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2465
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2466 These are the ``Raw Unicode Esacpe'' codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2467
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2468 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2469 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2470 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2471 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
2472 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
2473 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2474 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2475
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2476 \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
2477 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2478 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2479 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
2480 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
2481 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2482 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2483
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2484 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2485 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
2486 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
2487 \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
2488 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2489
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2490 % --- Latin-1 Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2491
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2492 These are the Latin-1 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2493
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2494 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
2495 are accepted by the codecs during encoding.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2496
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2497 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2498 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2499 const char *errors}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2500 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
2501 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
2502 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2503 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2504
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2505 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2506 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2507 const char *errors}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2508 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
2509 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
2510 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2511 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2512
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2513 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2514 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
2515 Python string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2516 \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
2517 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2518
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2519 % --- ASCII Codecs -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2520
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2521 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
2522 accepted. All other codes generate errors.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2523
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2524 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2525 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2526 const char *errors}
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2527 Creates a Unicode object by decoding \var{size} bytes of the
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2528 \ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2529 was raised by the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2530 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2531
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2532 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2533 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2534 const char *errors}
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2535 Encodes the \ctype{Py_UNICODE} buffer of the given size using
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2536 \ASCII{} and returns a Python string object. Returns \NULL{} in case
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2537 an exception was raised by the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2538 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2539
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2540 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2541 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
2542 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2543 \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
2544 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2545
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2546 % --- Character Map Codecs -----------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2547
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2548 These are the mapping codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2549
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2550 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
2551 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
2552 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
2553 codec uses mapping to encode and decode characters.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2554
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2555 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
2556 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
2557 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
2558
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2559 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
2560 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
2561 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
2562
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2563 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
2564 interface.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2565
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2566 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
2567 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
2568 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
2569 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
2570 points.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2571
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2572 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2573 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2574 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2575 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2576 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
2577 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
2578 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
2579 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2580
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2581 \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
2582 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2583 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2584 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2585 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
2586 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
2587 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
2588 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2589
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2590 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2591 PyObject *mapping}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2592 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
2593 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
2594 ``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
2595 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2596 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2597
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2598 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
2599
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2600 \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
2601 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2602 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2603 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2604 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
2605 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
2606 Unicode object. Returns \NULL{} when an exception was raised by the
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2607 codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2608
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2609 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
2610 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
2611
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2612 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2613 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
2614 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
2615 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2616
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2617 % --- MBCS codecs for Windows --------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2618
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2619 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
2620 Windows and use the Win32 MBCS converters to implement the
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2621 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
2622 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
2623 machine running the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2624
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2625 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2626 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2627 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2628 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
2629 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
2630 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2631 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2632
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2633 \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
2634 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2635 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2636 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
2637 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
2638 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2639 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2640
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2641 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2642 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
2643 string object. Error handling is ``strict''. Returns \NULL{} in case
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2644 an exception was raised by the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2645 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2646
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2647 % --- Methods & Slots ----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2648
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2649 \subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2650
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2651 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
2652 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
2653 Unicode objects or integers as apporpriate.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2654
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2655 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
2656
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2657 \begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2658 PyObject *right}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2659 Concat two strings giving a new Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2660 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2661
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2662 \begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2663 PyObject *sep,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2664 int maxsplit}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2665 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
2666
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2667 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
2668 substrings. Otherwise, splits occur at the given separator.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2669
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2670 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
2671
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2672 Separators are not included in the resulting list.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2673 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2674
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2675 \begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2676 int maxsplit}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2677 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
2678 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
2679 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
2680 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2681
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2682 \begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2683 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2684 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2685 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
2686 return the resulting Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2687
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2688 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
2689 integers or None (causing deletion of the character).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2690
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2691 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2692 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
2693 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
2694
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2695 \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
2696 which indicates to use the default error handling.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2697 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2698
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2699 \begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2700 PyObject *seq}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2701 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
2702 the resulting Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2703 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2704
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2705 \begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2706 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2707 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2708 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2709 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2710 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
2711 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
2712 \var{direction} == 1 a suffix match), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2713 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2714
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2715 \begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2716 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2717 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2718 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2719 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2720 Return the first position of \var{substr} in
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2721 \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
2722 (\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
2723 \var{direction} == -1 a backward search), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2724 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2725
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2726 \begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2727 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2728 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2729 int end}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2730 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
2731 \var{str}[\var{start}:\var{end}]
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2732 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2733
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2734 \begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2735 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2736 PyObject *replstr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2737 int maxcount}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2738 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
2739 \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
2740 \var{maxcount} == -1 means: replace all occurrences.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2741 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2742
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2743 \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
2744 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
2745 greater than resp.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2746 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2747
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2748 \begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2749 PyObject *args}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2750 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
2751 analogous to \code{\var{format} \%\ \var{args}}. The
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2752 \var{args} argument must be a tuple.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2753 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2754
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2755 \begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2756 PyObject *element}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2757 Checks whether \var{element} is contained in \var{container} and
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2758 returns true or false accordingly.
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2759
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2760 \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
2761 returned in case of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2762 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2763
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2764
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2765 \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
2766 \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
2767
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2768 \obindex{buffer}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2769 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
2770 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
2771 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
2772 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
2773 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
2774
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2775 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
2776 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
2777 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
2778 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
2779 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
2780
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2781 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
2782 \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
2783 through the buffer interface can be written to a file. There are a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2784 number of format codes to \cfunction{PyArgs_ParseTuple()} that operate
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2785 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
2786 object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2787
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2788 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
2789 ``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
2790 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
2791
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2792 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
2793 (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
2794 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
2795 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
2796 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
2797 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
2798 interface.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2799
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2800 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
2801 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
2802 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
2803 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
2804 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
2805 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
2806 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
2807 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
2808 format.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2809
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2810 \begin{ctypedesc}{PyBufferObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2811 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
2812 \end{ctypedesc}
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2813
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2814 \begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2815 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
2816 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
2817 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
2818 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2819
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2820 \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
2821 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
2822 \cfunction{PyBuffer_FromObject()} or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2823 \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
2824 \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
2825 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
2826 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
2827 length.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2828 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2829
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2830 \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
2831 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
2832 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2833
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2834 \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
2835 int offset, int size}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2836 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
2837 \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
2838 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
2839 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
2840 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
2841 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
2842 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
2843 \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
2844 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
2845 \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
2846 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2847
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2848 \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
2849 int offset,
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2850 int size}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2851 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
2852 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
2853 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
2854 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
2855 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2856
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2857 \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
2858 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
2859 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
2860 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
2861 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
2862 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
2863 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
2864 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
2865 that case.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2866 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2867
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2868 \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
2869 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
2870 is writable.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2871 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2872
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2873 \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
2874 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
2875 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
2876 \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
2877 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2878
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
2879
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2880 \subsection{Tuple Objects \label{tupleObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2881
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2882 \obindex{tuple}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2883 \begin{ctypedesc}{PyTupleObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
2884 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
2885 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2886
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2887 \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
2888 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
2889 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
2890 layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2891 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2892
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2893 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2894 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
2895 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2896
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2897 \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
2898 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
2899 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2900
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2901 \begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2902 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
2903 of that tuple.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2904 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2905
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2906 \begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyTupleObject *p, int pos}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2907 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
2908 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
2909 sets an \exception{IndexError} exception.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2910 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2911
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2912 \begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2913 Does the same, but does no checking of its arguments.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2914 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2915
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2916 \begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyTupleObject *p,
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2917 int low,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2918 int high}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2919 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
2920 \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
2921 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2922
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2923 \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
2924 int pos, PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2925 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
2926 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
2927 \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
2928 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2929
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2930 \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
2931 int pos, PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2932 Does the same, but does no error checking, and
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2933 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
2934 \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
2935 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2936
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2937 \begin{cfuncdesc}{int}{_PyTuple_Resize}{PyTupleObject *p,
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2938 int newsize, int last_is_sticky}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2939 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
2940 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
2941 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
2942 Do \emph{not} use this if the tuple may already be known to some other
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2943 part of the code. \var{last_is_sticky} is a flag --- if true, the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2944 tuple will grow or shrink at the front, otherwise it will grow or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2945 shrink at the end. Think of this as destroying the old tuple and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2946 creating a new one, only more efficiently. Returns \code{0} on
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2947 success and \code{-1} on failure (in which case a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2948 \exception{MemoryError} or \exception{SystemError} will be raised).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2949 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2950
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2951
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2952 \subsection{List Objects \label{listObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2953
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2954 \obindex{list}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2955 \begin{ctypedesc}{PyListObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
2956 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
2957 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2958
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2959 \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
2960 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
2961 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
2962 \withsubitem{(in module types)}{\ttindex{ListType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2963 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2964
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2965 \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
2966 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
2967 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2968
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2969 \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
2970 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
2971 failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2972 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2973
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2974 \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
2975 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
2976 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
2977 \bifuncindex{len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2978 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2979
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2980 \begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2981 Macro form of \cfunction{PyList_GetSize()} without error checking.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2982 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2983
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2984 \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
2985 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
2986 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
2987 sets an \exception{IndexError} exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2988 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2989
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2990 \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
2991 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
2992 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2993
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2994 \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2995 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
2996 Sets the item at index \var{index} in list to \var{item}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2997 \strong{Note:} This function ``steals'' a reference to \var{item}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2998 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2999
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3000 \begin{cfuncdesc}{PyObject*}{PyList_SET_ITEM}{PyObject *list, int i,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3001 PyObject *o}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3002 Macro form of \cfunction{PyList_SetItem()} without error checking.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3003 \strong{Note:} This function ``steals'' a reference to \var{item}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3004 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3005
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3006 \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
3007 PyObject *item}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3008 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
3009 \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
3010 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
3011 \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
3012 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3013
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3014 \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
3015 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
3016 \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
3017 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
3018 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3019
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3020 \begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3021 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
3022 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
3023 \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
3024 exception if unsuccessful.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3025 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
3026 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3027
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3028 \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3029 int low, int high,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3030 PyObject *itemlist}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3031 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
3032 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
3033 \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
3034 \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
3035 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3036
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3037 \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
3038 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
3039 \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
3040 \samp{\var{list}.sort()}.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3041 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3042
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3043 \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
3044 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
3045 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
3046 \samp{\var{list}.reverse()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3047 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3048
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3049 \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
3050 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
3051 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
3052 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3053
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3054
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3055 \section{Mapping Objects \label{mapObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3056
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3057 \obindex{mapping}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3058
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3059
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3060 \subsection{Dictionary Objects \label{dictObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3061
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3062 \obindex{dictionary}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3063 \begin{ctypedesc}{PyDictObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3064 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
3065 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3066
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3067 \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
3068 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
3069 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
3070 \code{types.DictionaryType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3071 \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
3072 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3073
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3074 \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
3075 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
3076 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3077
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3078 \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
3079 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
3080 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3081
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3082 \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
3083 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
3084 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3085
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
3086 \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
3087 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
3088 Empties an existing dictionary of all key-value pairs.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3089 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3090
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3091 \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
3092 PyObject *val}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3093 Inserts \var{value} into the dictionary with a key of \var{key}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3094 \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
3095 raised.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3096 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3097
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3098 \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3099 char *key,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3100 PyObject *val}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3101 Inserts \var{value} into the dictionary using \var{key}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3102 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
3103 created using \code{PyString_FromString(\var{key})}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3104 \ttindex{PyString_FromString()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3105 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3106
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3107 \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
3108 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
3109 \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
3110 raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3111 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3112
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3113 \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
3114 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
3115 specified by the string \var{key}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3116 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3117
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3118 \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
3119 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
3120 \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
3121 \emph{without} setting an exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3122 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3123
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3124 \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
3125 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
3126 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
3127 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3128
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3129 \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
3130 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
3131 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
3132 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
3133 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3134
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3135 \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
3136 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
3137 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
3138 \citetitle[../lib/lib.html]{Python Library Reference}).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3139 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3140
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3141 \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
3142 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
3143 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
3144 \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
3145 Reference}).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3146 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3147
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3148 \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
3149 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
3150 \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
3151 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3152
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
3153 \begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p, int *ppos,
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
3154 PyObject **pkey, PyObject **pvalue}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3155
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3156 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3157
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3158
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3159 \section{Numeric Objects \label{numericObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3160
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3161 \obindex{numeric}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3162
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3163
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3164 \subsection{Plain Integer Objects \label{intObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3165
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3166 \obindex{integer}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3167 \begin{ctypedesc}{PyIntObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3168 This subtype of \ctype{PyObject} represents a Python integer object.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3169 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3170
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3171 \begin{cvardesc}{PyTypeObject}{PyInt_Type}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3172 This instance of \ctype{PyTypeObject} represents the Python plain
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3173 integer type. This is the same object as \code{types.IntType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3174 \withsubitem{(in modules types)}{\ttindex{IntType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3175 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3176
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3177 \begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3178 Returns true if \var{o} is of type \cdata{PyInt_Type}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3179 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3180
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3181 \begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3182 Creates a new integer object with a value of \var{ival}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3183
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3184 The current implementation keeps an array of integer objects for all
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3185 integers between \code{-1} and \code{100}, when you create an int in
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3186 that range you actually just get back a reference to the existing
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3187 object. So it should be possible to change the value of \code{1}. I
7807
5d15f4fd6d69 Capitalize "Python" for consistency.
Fred Drake <fdrake@acm.org>
parents: 7782
diff changeset
3188 suspect the behaviour of Python in this case is undefined. :-)
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3189 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3190
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3191 \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3192 Will first attempt to cast the object to a \ctype{PyIntObject}, if
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3193 it is not already one, and then return its value.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3194 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3195
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3196 \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3197 Returns the value of the object \var{io}. No error checking is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3198 performed.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3199 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3200
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3201 \begin{cfuncdesc}{long}{PyInt_GetMax}{}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3202 Returns the system's idea of the largest integer it can handle
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3203 (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3204 header files).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3205 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3206
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3207
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3208 \subsection{Long Integer Objects \label{longObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3209
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3210 \obindex{long integer}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3211 \begin{ctypedesc}{PyLongObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3212 This subtype of \ctype{PyObject} represents a Python long integer
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3213 object.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3214 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3215
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3216 \begin{cvardesc}{PyTypeObject}{PyLong_Type}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3217 This instance of \ctype{PyTypeObject} represents the Python long
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3218 integer type. This is the same object as \code{types.LongType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3219 \withsubitem{(in modules types)}{\ttindex{LongType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3220 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3221
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3222 \begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3223 Returns true if its argument is a \ctype{PyLongObject}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3224 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3225
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3226 \begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3227 Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{} on
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3228 failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3229 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3230
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3231 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3232 Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3233 long}, or \NULL{} on failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3234 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3235
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3236 \begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3237 Returns a new \ctype{PyLongObject} object from the integer part of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3238 \var{v}, or \NULL{} on failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3239 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3240
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3241 \begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3242 Returns a C \ctype{long} representation of the contents of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3243 \var{pylong}. If \var{pylong} is greater than
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3244 \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3245 raised.\withsubitem{(built-in exception)}{OverflowError}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3246 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3247
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3248 \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3249 Returns a C \ctype{unsigned long} representation of the contents of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3250 \var{pylong}. If \var{pylong} is greater than
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3251 \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3252 is raised.\withsubitem{(built-in exception)}{OverflowError}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3253 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3254
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3255 \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3256 Returns a C \ctype{double} representation of the contents of \var{pylong}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3257 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3258
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3259 \begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3260 int base}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3261 Return a new \ctype{PyLongObject} based on the string value in
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3262 \var{str}, which is interpreted according to the radix in \var{base}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3263 If \var{pend} is non-\NULL, \code{*\var{pend}} will point to the first
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3264 character in \var{str} which follows the representation of the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3265 number. If \var{base} is \code{0}, the radix will be determined base
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3266 on the leading characters of \var{str}: if \var{str} starts with
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3267 \code{'0x'} or \code{'0X'}, radix 16 will be used; if \var{str} starts
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3268 with \code{'0'}, radix 8 will be used; otherwise radix 10 will be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3269 used. If \var{base} is not \code{0}, it must be between \code{2} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3270 \code{36}, inclusive. Leading spaces are ignored. If there are no
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3271 digits, \exception{ValueError} will be raised.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3272 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3273
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3274
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3275 \subsection{Floating Point Objects \label{floatObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3276
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3277 \obindex{floating point}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3278 \begin{ctypedesc}{PyFloatObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3279 This subtype of \ctype{PyObject} represents a Python floating point
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3280 object.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3281 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3282
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3283 \begin{cvardesc}{PyTypeObject}{PyFloat_Type}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3284 This instance of \ctype{PyTypeObject} represents the Python floating
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3285 point type. This is the same object as \code{types.FloatType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3286 \withsubitem{(in modules types)}{\ttindex{FloatType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3287 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3288
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3289 \begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3290 Returns true if its argument is a \ctype{PyFloatObject}.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
3291 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
3292
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3293 \begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3294 Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3295 failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3296 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3297
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3298 \begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3299 Returns a C \ctype{double} representation of the contents of \var{pyfloat}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3300 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3301
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3302 \begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3303 Returns a C \ctype{double} representation of the contents of
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3304 \var{pyfloat}, but without error checking.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3305 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3306
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3307
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3308 \subsection{Complex Number Objects \label{complexObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3309
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3310 \obindex{complex number}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3311 Python's complex number objects are implemented as two distinct types
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3312 when viewed from the C API: one is the Python object exposed to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3313 Python programs, and the other is a C structure which represents the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3314 actual complex number value. The API provides functions for working
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3315 with both.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3316
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3317 \subsubsection{Complex Numbers as C Structures}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3318
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3319 Note that the functions which accept these structures as parameters
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3320 and return them as results do so \emph{by value} rather than
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3321 dereferencing them through pointers. This is consistent throughout
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3322 the API.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3323
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3324 \begin{ctypedesc}{Py_complex}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3325 The C structure which corresponds to the value portion of a Python
7310
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
3326 complex number object. Most of the functions for dealing with complex
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
3327 number objects use structures of this type as input or output values,
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
3328 as appropriate. It is defined as:
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
3329
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3330 \begin{verbatim}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3331 typedef struct {
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3332 double real;
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3333 double imag;
7310
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
3334 } Py_complex;
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3335 \end{verbatim}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3336 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3337
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3338 \begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3339 Return the sum of two complex numbers, using the C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3340 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3341 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3342
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3343 \begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3344 Return the difference between two complex numbers, using the C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3345 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3346 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3347
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3348 \begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3349 Return the negation of the complex number \var{complex}, using the C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3350 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3351 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3352
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3353 \begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3354 Return the product of two complex numbers, using the C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3355 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3356 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3357
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3358 \begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3359 Py_complex divisor}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3360 Return the quotient of two complex numbers, using the C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3361 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3362 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3363
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3364 \begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3365 Return the exponentiation of \var{num} by \var{exp}, using the C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3366 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3367 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3368
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3369
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3370 \subsubsection{Complex Numbers as Python Objects}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3371
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3372 \begin{ctypedesc}{PyComplexObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3373 This subtype of \ctype{PyObject} represents a Python complex number object.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3374 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3375
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3376 \begin{cvardesc}{PyTypeObject}{PyComplex_Type}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3377 This instance of \ctype{PyTypeObject} represents the Python complex
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3378 number type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3379 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3380
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3381 \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3382 Returns true if its argument is a \ctype{PyComplexObject}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3383 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3384
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3385 \begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3386 Create a new Python complex number object from a C
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3387 \ctype{Py_complex} value.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3388 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3389
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3390 \begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3391 Returns a new \ctype{PyComplexObject} object from \var{real} and \var{imag}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3392 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3393
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3394 \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3395 Returns the real part of \var{op} as a C \ctype{double}.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
3396 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
3397
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3398 \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3399 Returns the imaginary part of \var{op} as a C \ctype{double}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3400 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3401
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3402 \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3403 Returns the \ctype{Py_complex} value of the complex number \var{op}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3404 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3405
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3406
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3407
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3408 \section{Other Objects \label{otherObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3409
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3410 \subsection{File Objects \label{fileObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3411
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3412 \obindex{file}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3413 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
3414 \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
3415 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
3416
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3417 \begin{ctypedesc}{PyFileObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3418 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
3419 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3420
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3421 \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
3422 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
3423 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
3424 \withsubitem{(in module types)}{\ttindex{FileType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3425 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3426
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3427 \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
3428 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
3429 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3430
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3431 \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
3432 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
3433 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
3434 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
3435 \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
3436 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3437
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3438 \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
3439 char *name, char *mode,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3440 int (*close)(FILE*)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3441 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
3442 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
3443 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
3444 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3445
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3446 \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
3447 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
3448 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3449
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3450 \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
3451 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
3452 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
3453 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
3454 \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
3455 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
3456 \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
3457 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
3458 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
3459 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
3460 \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
3461 immediately.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3462 \withsubitem{(built-in exception)}{\ttindex{EOFError}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3463 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3464
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3465 \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
3466 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
3467 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3468
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3469 \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
3470 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
3471 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
3472 creation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3473 \end{cfuncdesc}
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 \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
3476 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
3477 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
3478 \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
3479 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
3480 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
3481 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
3482 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
3483 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
3484 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
3485 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
3486 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3487
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3488 \begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3489 int flags}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3490 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
3491 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
3492 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
3493 \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
3494 failure; the appropriate exception will be set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3495 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3496
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3497 \begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3498 int flags}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3499 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
3500 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
3501 set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3502 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3503
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3504
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3505 \subsection{Module Objects \label{moduleObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3506
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3507 \obindex{module}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3508 There are only a few functions special to module objects.
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3509
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3510 \begin{cvardesc}{PyTypeObject}{PyModule_Type}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3511 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
3512 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
3513 \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
3514 \end{cvardesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3515
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3516 \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
3517 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
3518 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3519
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3520 \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
3521 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
3522 \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
3523 \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
3524 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
3525 \withsubitem{(module attribute)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3526 \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
3527 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3528
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3529 \begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3530 Return the dictionary object that implements \var{module}'s namespace;
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3531 this object is the same as the \member{__dict__} attribute of the
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3532 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
3533 \withsubitem{(module attribute)}{\ttindex{__dict__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3534 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3535
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3536 \begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3537 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
3538 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
3539 raised and \NULL{} is returned.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3540 \withsubitem{(module attribute)}{\ttindex{__name__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3541 \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
3542 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3543
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3544 \begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3545 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
3546 \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
3547 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
3548 \NULL.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3549 \withsubitem{(module attribute)}{\ttindex{__file__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3550 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3551 \end{cfuncdesc}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3552
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3553
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3554 \subsection{CObjects \label{cObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3555
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3556 \obindex{CObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3557 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
3558 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
3559 information on using these objects.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3560
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3561
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3562 \begin{ctypedesc}{PyCObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3563 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
3564 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
3565 \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
3566 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
3567 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
3568 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
3569 \end{ctypedesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3570
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3571 \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
3572 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
3573 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3574
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3575 \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj,
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3576 void (*destr)(void *)}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3577 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
3578 \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
3579 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
3580 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3581
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3582 \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj,
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3583 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
3584 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
3585 \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
3586 \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
3587 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
3588 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3589
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3590 \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
3591 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
3592 \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
3593 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3594
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3595 \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
3596 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
3597 \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
3598 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3599
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3600
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3601 \chapter{Initialization, Finalization, and Threads
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3602 \label{initialization}}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3603
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3604 \begin{cfuncdesc}{void}{Py_Initialize}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3605 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
3606 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
3607 functions; with the exception of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3608 \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
3609 \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
3610 \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
3611 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
3612 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
3613 \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
3614 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
3615 \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
3616 \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
3617 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
3618 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
3619 \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
3620 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
3621 \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
3622 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
3623 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
3624
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
3625 \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
3626 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
3627 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
3628 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
3629 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3630 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3631
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3632 \begin{cfuncdesc}{void}{Py_Finalize}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3633 Undo all initializations made by \cfunction{Py_Initialize()} and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3634 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
3635 sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3636 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
3637 \cfunction{Py_Initialize()}. Ideally, this frees all memory allocated
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3638 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
3639 time (without calling \cfunction{Py_Initialize()} again first). There
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3640 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
3641
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3642 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
3643 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
3644 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
3645 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
3646 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
3647 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
3648 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
3649
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3650 \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
3651 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
3652 (\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
3653 (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
3654 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
3655 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
3656 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
3657 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
3658 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
3659 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
3660 calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3661 than once.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3662 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3663
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3664 \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
3665 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
3666 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
3667 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
3668 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
3669 \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
3670 \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
3671 \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
3672 (\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
3673 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
3674 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
3675 \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
3676 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
3677 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3678 \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
3679
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3680 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
3681 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
3682 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
3683 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
3684 \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
3685 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
3686 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
3687 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
3688 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
3689 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
3690
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3691 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
3692 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
3693 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
3694 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
3695 (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
3696 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
3697 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
3698 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
3699 re-initialized by calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3700 \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
3701 \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
3702 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
3703 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3704
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3705 \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
3706 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
3707 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
3708 \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
3709 \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
3710 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
3711 (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
3712 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
3713 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
3714 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
3715 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
3716 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
3717 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
3718 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
3719 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
3720 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
3721 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3722
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3723 \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
3724 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
3725 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
3726 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
3727 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
3728 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
3729 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
3730 \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
3731 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
3732 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3733
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3734 \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
3735 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
3736 \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
3737 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
3738 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
3739 \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
3740 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
3741 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
3742 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
3743 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
3744 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
3745 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
3746 the contents of this storage.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3747 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3748
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3749 \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
3750 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
3751 \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
3752 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
3753 should not modify its value.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3754 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3755
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3756 \begin{cfuncdesc}{char*}{Py_GetPrefix}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3757 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
3758 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
3759 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
3760 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
3761 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
3762 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
3763 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
3764 \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
3765 \program{configure} script at build time. The value is available to
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
3766 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
3767 also the next function.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3768 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3769
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3770 \begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3771 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
3772 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
3773 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
3774 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
3775 \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
3776 \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
3777 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
3778 \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
3779 \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
3780 \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
3781 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
3782
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3783 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
3784 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
3785 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
3786 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
3787 \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
3788 installed in \file{/usr/local}.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3789
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3790 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
3791 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
3792 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
3793 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
3794 Linux are yet another platform. Different major revisions of the same
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
3795 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
3796 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
3797 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
3798 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
3799 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
3800 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
3801
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3802 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
3803 \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
3804 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
3805 platform.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3806 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3807
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3808 \begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3809 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
3810 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
3811 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
3812 \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
3813 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
3814 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
3815 \code{sys.executable}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3816 \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
3817 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3818
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3819 \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
3820 \indexiii{module}{search}{path}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3821 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
3822 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
3823 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
3824 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
3825 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
3826 DOS/Windows, and \character{\e n} (the \ASCII{} newline character) on
7271
0061d3916ae4 "ASCII" --> "\ASCII{}"
Fred Drake <fdrake@acm.org>
parents: 7269
diff changeset
3827 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
3828 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
3829 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
3830 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
3831 modules.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3832
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3833 % XXX should give the exact rules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3834 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3835
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3836 \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
3837 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
3838 looks something like
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3839
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
3840 \begin{verbatim}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3841 "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
3842 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3843
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3844 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
3845 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
3846 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
3847 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
3848 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
3849 \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
3850 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3851
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3852 \begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
3853 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
3854 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
3855 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
3856 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
3857 \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
3858 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
3859 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
3860 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
3861 \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
3862 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3863
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3864 \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
3865 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
3866 for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3867
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
3868 \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
3869
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3870 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
3871 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
3872 \code{sys.copyright}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3873 \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
3874 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3875
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3876 \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
3877 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
3878 version, in square brackets, for example:
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3879
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3880 \begin{verbatim}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3881 "[GCC 2.7.2.2]"
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3882 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3883
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3884 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
3885 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
3886 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
3887 \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
3888 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3889
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3890 \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
3891 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
3892 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
3893
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
3894 \begin{verbatim}
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
3895 "#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
3896 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3897
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3898 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
3899 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
3900 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
3901 \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
3902 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3903
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3904 \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
3905 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
3906 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
3907 \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
3908 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
3909 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
3910 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
3911 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
3912 condition is signalled using
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3913 \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
3914 \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
3915 % 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
3916 % check w/ Guido.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3917 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3918
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3919 % 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
3920
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3921 \section{Thread State and the Global Interpreter Lock
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3922 \label{threads}}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3923
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3924 \index{global interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3925 \index{interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3926 \index{lock, interpreter}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3927
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3928 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
3929 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
3930 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
3931 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
3932 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
3933 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
3934 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
3935
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3936 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
3937 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
3938 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
3939 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
3940 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
3941 \withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3942 \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
3943 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
3944 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
3945 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
3946
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3947 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
3948 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
3949 \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
3950 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
3951 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
3952 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
3953 \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
3954 \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
3955 current thread.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3956
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3957 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
3958 \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
3959 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
3960 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
3961 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
3962 manipulated explicitly.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3963
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3964 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
3965 interpreter lock has the following simple structure:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3966
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
3967 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3968 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
3969 Release the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3970 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3971 Reacquire the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3972 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
3973 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3974
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3975 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
3976
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
3977 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3978 Py_BEGIN_ALLOW_THREADS
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3979 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3980 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
3981 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3982
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3983 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
3984 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
3985 \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
3986 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
3987 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
3988 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
3989
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3990 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
3991 following code:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3992
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
3993 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3994 PyThreadState *_save;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3995
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3996 _save = PyEval_SaveThread();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3997 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3998 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
3999 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4000
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4001 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
4002 as follows:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4003
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4004 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4005 PyThreadState *_save;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4006
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4007 _save = PyThreadState_Swap(NULL);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4008 PyEval_ReleaseLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4009 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4010 PyEval_AcquireLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4011 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
4012 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4013
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4014 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
4015 \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
4016 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
4017 \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
4018 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
4019 is disabled,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4020 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4021 \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
4022 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
4023 \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
4024 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
4025 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
4026 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
4027
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4028 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
4029 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
4030 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
4031 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
4032 lock and store its own thread state in the global variable).
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4033 Reversely, when acquiring the lock and restoring the thread state, the
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4034 lock must be acquired before storing the thread state pointer.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4035
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4036 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
4037 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
4038 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
4039 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
4040 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
4041 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
4042 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
4043 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
4044 structure.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4045
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4046 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
4047 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
4048 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
4049 interpreter, for example the module administration
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4050 (\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
4051 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
4052 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
4053 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
4054 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
4055 thread after Python is initialized).
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4056
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4057
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4058 \begin{ctypedesc}{PyInterpreterState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4059 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
4060 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
4061 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
4062 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
4063
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4064 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
4065 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
4066 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
4067 regardless of to which interpreter they belong.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4068 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4069
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4070 \begin{ctypedesc}{PyThreadState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4071 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
4072 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
4073 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
4074 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4075
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4076 \begin{cfuncdesc}{void}{PyEval_InitThreads}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4077 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
4078 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
4079 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
4080 \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
4081 \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
4082 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
4083 \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
4084 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4085
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4086 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
4087 this function before calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4088 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4089
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4090 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
4091 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
4092 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
4093 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
4094 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
4095 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
4096 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
4097 \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
4098 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
4099 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
4100 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
4101 has acquired it.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4102
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4103 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
4104 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
4105
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4106 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
4107 compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4108 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4109
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4110 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4111 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
4112 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
4113 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
4114 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4115 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4116
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4117 \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4118 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
4119 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
4120 disabled at compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4121 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4122
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4123 \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
4124 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
4125 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
4126 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
4127 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
4128 is disabled at compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4129 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4130
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4131 \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
4132 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
4133 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
4134 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
4135 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
4136 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
4137 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
4138 time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4139 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4140
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4141 \begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4142 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
4143 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
4144 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
4145 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
4146 (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
4147 compile time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4148 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4149
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4150 \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4151 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
4152 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
4153 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
4154 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
4155 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
4156 time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4157 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4158
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4159 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
4160 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
4161
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4162 \begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4163 This macro expands to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4164 \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4165 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
4166 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
4167 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
4168 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4169 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4170
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4171 \begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4172 This macro expands to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4173 \samp{PyEval_RestoreThread(_save); \}}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4174 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
4175 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
4176 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
4177 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4178 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4179
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4180 \begin{csimplemacrodesc}{Py_BEGIN_BLOCK_THREADS}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4181 This macro expands to \samp{PyEval_RestoreThread(_save);} i.e. it
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4182 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
4183 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
4184 time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4185 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4186
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4187 \begin{csimplemacrodesc}{Py_BEGIN_UNBLOCK_THREADS}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4188 This macro expands to \samp{_save = PyEval_SaveThread();} i.e. it is
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4189 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
4190 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
4191 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4192 \end{csimplemacrodesc}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4193
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4194 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
4195 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
4196 interpreter lock has been created.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4197
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4198 \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
4199 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
4200 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
4201 function.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4202 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4203
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4204 \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4205 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
4206 lock must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4207 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4208
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4209 \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4210 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
4211 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
4212 call to \cfunction{PyInterpreterState_Clear()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4213 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4214
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4215 \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
4216 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
4217 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
4218 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
4219 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4220
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4221 \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4222 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
4223 must be held.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4224 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4225
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4226 \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4227 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
4228 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
4229 call to \cfunction{PyThreadState_Clear()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4230 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4231
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4232 \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4233 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
4234 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
4235 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
4236 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4237
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4238 \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
4239 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
4240 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
4241 must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4242 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4243
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4244
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4245 \chapter{Memory Management \label{memory}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4246 \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
4247
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4248
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4249 \section{Overview \label{memoryOverview}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4250
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4251 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
4252 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
4253 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
4254 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
4255 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
4256 preallocation or caching.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4257
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4258 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
4259 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
4260 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
4261 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
4262 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
4263 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
4264 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
4265 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
4266 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
4267 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
4268 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
4269 the private heap.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4270
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4271 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
4272 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
4273 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
4274 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
4275 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
4276 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
4277 this document.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4278
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4279 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
4280 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
4281 library: \cfunction{malloc()}\ttindex{malloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4282 \cfunction{calloc()}\ttindex{calloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4283 \cfunction{realloc()}\ttindex{realloc()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4284 \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
4285 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
4286 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
4287 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
4288 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
4289 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
4290
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4291 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4292 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4293 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
4294
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4295 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4296 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4297 ...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
4298 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4299 free(buf); /* malloc'ed */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4300 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4301 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4302
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4303 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
4304 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
4305 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
4306
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4307 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
4308 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
4309 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
4310 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
4311 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
4312 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
4313 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
4314 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
4315 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
4316 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
4317 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
4318 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
4319 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
4320 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
4321 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
4322
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4323
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4324 \section{Memory Interface \label{memoryInterface}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4325
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4326 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
4327 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
4328
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4329
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4330 \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
4331 Allocates \var{n} bytes and returns a pointer of type \ctype{void*} to
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4332 the allocated memory, or \NULL{} if the request fails. Requesting zero
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4333 bytes returns a non-\NULL{} pointer.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4334 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4335
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4336 \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
4337 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
4338 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
4339 sizes. If \var{p} is \NULL{}, the call is equivalent to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4340 \cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the memory block
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4341 is resized but is not freed, and the returned pointer is non-\NULL{}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4342 Unless \var{p} is \NULL{}, it must have been returned by a previous
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4343 call to \cfunction{PyMem_Malloc()} or \cfunction{PyMem_Realloc()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4344 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4345
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4346 \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
4347 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
4348 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
4349 \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
4350 \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
4351 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
4352 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4353
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4354 \begin{cfuncdesc}{void*}{Py_Malloc}{size_t n}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4355 Same as \cfunction{PyMem_Malloc()}, but calls
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4356 \cfunction{PyErr_NoMemory()} on failure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4357 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4358
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4359 \begin{cfuncdesc}{void*}{Py_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
4360 Same as \cfunction{PyMem_Realloc()}, but calls
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4361 \cfunction{PyErr_NoMemory()} on failure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4362 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4363
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4364 \begin{cfuncdesc}{void}{Py_Free}{void *p}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4365 Same as \cfunction{PyMem_Free()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4366 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4367
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4368 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
4369 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
4370
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4371 \begin{cfuncdesc}{\var{TYPE}*}{PyMem_NEW}{TYPE, size_t n}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4372 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
4373 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
4374 \ctype{\var{TYPE}*}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4375 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4376
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4377 \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
4378 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
4379 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
4380 cast to \ctype{\var{TYPE}*}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4381 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4382
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4383 \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
4384 Same as \cfunction{PyMem_Free()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4385 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4386
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4387
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4388 \section{Examples \label{memoryExamples}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4389
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4390 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
4391 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
4392 first function set:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4393
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4394 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4395 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4396 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
4397
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4398 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4399 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4400 /* ...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
4401 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4402 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
4403 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4404 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4405
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4406 With the second function set, the need to call
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4407 \cfunction{PyErr_NoMemory()} is obviated:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4408
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4409 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4410 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4411 char *buf = (char *) Py_Malloc(BUFSIZ); /* for I/O */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4412
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4413 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4414 return NULL;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4415 /* ...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
4416 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4417 Py_Free(buf); /* allocated with Py_Malloc */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4418 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4419 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4420
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4421 The same code using the macro set:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4422
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4423 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4424 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4425 char *buf = PyMem_NEW(char, BUFSIZ); /* for I/O */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4426
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4427 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4428 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4429 /* ...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
4430 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4431 PyMem_DEL(buf); /* allocated with PyMem_NEW */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4432 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4433 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4434
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4435 Note that in the three examples above, the buffer is always
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4436 manipulated via functions/macros belonging to the same set. Indeed, it
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4437 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
4438 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
4439 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
4440 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
4441 allocators operating on different heaps.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4442
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4443 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4444 char *buf1 = PyMem_NEW(char, BUFSIZ);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4445 char *buf2 = (char *) malloc(BUFSIZ);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4446 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
4447 ...
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4448 PyMem_DEL(buf3); /* Wrong -- should be PyMem_Free() */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4449 free(buf2); /* Right -- allocated via malloc() */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4450 free(buf1); /* Fatal -- should be PyMem_DEL() */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4451 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4452
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4453 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
4454 the Python heap, objects in Python are allocated and released with
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4455 \cfunction{_PyObject_New()}\ttindex{_PyObject_New()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4456 \cfunction{_PyObject_NewVar()}\ttindex{_PyObject_NewVar()}, or with
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4457 their corresponding macros
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4458 \cfunction{PyObject_NEW()}\ttindex{PyObject_NEW()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4459 \cfunction{PyObject_NEW_VAR()}\ttindex{PyObject_NEW_VAR()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4460
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
4461 \cfunction{_PyObject_New()}, \cfunction{_PyObject_NewVar()},
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 13150
diff changeset
4462 \cfunction{_PyObject_Del()}, or with their corresponding macros
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 13150
diff changeset
4463 \cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()},
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 13150
diff changeset
4464 \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
4465
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 13150
diff changeset
4466 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
4467 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
4468
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4469
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4470 \chapter{Defining New Object Types \label{newTypes}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4471
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4472 \begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4473 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4474
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4475 \begin{cfuncdesc}{PyObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4476 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4477
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4478 \begin{cfuncdesc}{\var{TYPE}}{_PyObject_NEW}{TYPE, PyTypeObject *type}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4479 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4480
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4481 \begin{cfuncdesc}{\var{TYPE}}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4482 int size}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4483 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4484
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
4485 Py_InitModule (!!!)
5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes.
Guido van Rossum <guido@python.org>
parents: 8029
diff changeset
4486
5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes.
Guido van Rossum <guido@python.org>
parents: 8029
diff changeset
4487 PyArg_ParseTupleAndKeywords, PyArg_ParseTuple, PyArg_Parse
5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes.
Guido van Rossum <guido@python.org>
parents: 8029
diff changeset
4488
5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes.
Guido van Rossum <guido@python.org>
parents: 8029
diff changeset
4489 Py_BuildValue
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4490
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4491 DL_IMPORT
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4492
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4493 Py*_Check
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4494
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4495 _Py_NoneStruct
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4496
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4497
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4498 \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
4499
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4500 PyObject, PyVarObject
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4501
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4502 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
4503
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4504 Typedefs:
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4505 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
4506 intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4507 destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4508 setattrofunc, cmpfunc, reprfunc, hashfunc
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4509
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4510 \begin{ctypedesc}{PyCFunction}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4511 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
4512 \end{ctypedesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4513
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4514 \begin{ctypedesc}{PyMethodDef}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4515 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
4516 structure has four fields:
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4517
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4518 \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
4519 \lineiii{ml_name}{char *}{name of the method}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4520 \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
4521 \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
4522 constructed}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4523 \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
4524 \end{tableiii}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4525 \end{ctypedesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4526
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4527 \begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef[] table,
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4528 PyObject *ob, char *name}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4529 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
4530 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
4531 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
4532 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4533
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4534
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4535 \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
4536
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4537 \begin{ctypedesc}{PyMappingMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4538 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
4539 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
4540 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4541
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4542
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4543 \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
4544
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4545 \begin{ctypedesc}{PyNumberMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4546 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
4547 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
4548 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4549
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4550
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4551 \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
4552
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4553 \begin{ctypedesc}{PySequenceMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4554 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
4555 to implement the sequence protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4556 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4557
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4558
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4559 \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
4560 \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
4561
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4562 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
4563 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
4564 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
4565 \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
4566
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4567 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
4568 \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
4569 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
4570 a \ctype{PyBufferProcs} structure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4571
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4572 \strong{Note:} It is very important that your
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4573 \ctype{PyTypeObject} structure uses \code{Py_TPFLAGS_DEFAULT} for the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4574 value of the \member{tp_flags} member rather than \code{0}. This
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4575 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
4576 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
4577 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
4578 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
4579
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4580 \begin{ctypedesc}{PyBufferProcs}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4581 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
4582 implementation of the buffer protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4583
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4584 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
4585 \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
4586 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
4587 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
4588 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
4589
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4590 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
4591 \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
4592 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
4593
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4594 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
4595 \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
4596 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
4597 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
4598 \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
4599
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4600 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
4601 \ctype{getcharbufferproc}. This slot will only be present if the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4602 \code{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4603 \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
4604 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
4605 \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
4606 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
4607 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
4608 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
4609 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
4610 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
4611 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
4612 \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
4613 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
4614 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
4615 have character-based content.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4616
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4617 \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
4618 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
4619 \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
4620 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4621
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4622 \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
4623 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
4624 \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
4625 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
4626 \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
4627 \end{datadesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4628
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4629 \begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4630 (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
4631 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
4632 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
4633 \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
4634 positive, and strictly less than the number of segments returned by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4635 the \member{bf_getsegcount} slot function. On success, returns
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4636 \code{0} and sets \code{*\var{ptrptr}} to a pointer to the buffer
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4637 memory.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4638 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4639
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4640 \begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4641 (PyObject *self, int segment, void **ptrptr)}
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
4642 Return a pointer to a writable memory buffer in \code{*\var{ptrptr}};
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
4643 the memory buffer must correspond to buffer segment \var{segment}.
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
4644 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
4645 \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
4646 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
4647 \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
4648 % 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
4649 % 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
4650 % 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
4651 % code.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
4652 \end{ctypedesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
4653
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4654 \begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4655 (PyObject *self, int *lenp)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4656 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
4657 \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
4658 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
4659 The function cannot fail.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4660 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4661
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4662 \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4663 (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
4664 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4665
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4666
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4667 % \chapter{Debugging \label{debugging}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4668 %
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4669 % 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
4670
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
4671
7708
4991aaab17bd Revert the index stuff to work better with LaTeX2HTML.
Fred Drake <fdrake@acm.org>
parents: 7620
diff changeset
4672 \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
4673
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
4674 \end{document}