Mercurial > cpython-lru_cache-weakref

annotate Doc/api/api.tex @ 12713:7efbb4e6afca legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
macfsn should always be included, like exceptions and site.
author Jack Jansen <jack.jansen@cwi.nl>
date Wed, 17 May 2000 13:27:09 +0000
parents 04802b7e8a1f
children 6618325574cb
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
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
213 Conversely, when calling a 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
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
600 \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
601 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
602 (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
603 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
604 result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
605 \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
606 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
607
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
608 \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
609 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
610 \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
611 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
612 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
613 get the exception information.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
614 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
615
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
616 \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
617 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
618 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
619 \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
620 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
621
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
622 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
623 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
624
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
625 \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
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
626 \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
627
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
628 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
629 int start}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
630 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
631 \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
632 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
633 must be evaluated many times.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
634 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
635
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
636 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
637 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
638 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
639 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
640 \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
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}{PyObject*}{PyRun_String}{char *str, int start,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
644 PyObject *globals,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
645 PyObject *locals}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
646 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
647 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
648 \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
649 the source code.
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
650
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
651 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
652 \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
653 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
654
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
655 \begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
656 int start, PyObject *globals,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
657 PyObject *locals}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
658 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
659 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
660 \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
661 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
662
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
663 \begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
664 int start}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
665 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
666 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
667 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
668 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
669 \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
670 \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
671 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
672 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
673 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
674
11222
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
675 \begin{cvardesc}{int}{Py_eval_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
676 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
677 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
678 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
679
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
680 \begin{cvardesc}{int}{Py_file_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
681 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
682 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
683 \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
684 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
685 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
686
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
687 \begin{cvardesc}{int}{Py_single_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
688 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
689 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
690 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
691 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
692
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
693
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
694 \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
695
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
696 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
697 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
698
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
699 \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
700 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
701 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
702 \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
703 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
704
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
705 \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
706 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
707 \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
708 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
709
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
710 \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
711 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
712 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
713 \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
714 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
715 invoked.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
716
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
717 \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
718 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
719 \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
720 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
721 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
722 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
723 \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
724 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
725 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
726 \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
727 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
728
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
729 \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
730 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
731 \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
732 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
733 applies.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
734 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
735
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
736 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
737 interpreter core: \cfunction{_Py_Dealloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
738 \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
739 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
740
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
741
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
742 \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
743
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
744 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
745 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
746 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
747 \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
748 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
749 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
750 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
751 \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
752 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
753 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
754 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
755 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
756 already set it.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
757
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
758 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
759 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
760 \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
761 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
762 \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
763 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
764 for each thread.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
765
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
766 % 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
767 % 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
768
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
769 \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
770 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
771 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
772 (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
773 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
774
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
775 \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
776 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
777 \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
778 \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
779 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
780 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
781 \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
782 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
783 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
784 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
785 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
786 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
787
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
788 \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
789 Equivalent to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
790 \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
791 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
792 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
793 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
794
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
795 \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
796 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
797 \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
798 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
799 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
800 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
801 occur.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
802 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
803
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
804 \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
805 Under certain circumstances, the values returned by
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
806 \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
807 \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
808 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
809 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
810 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
811 performance.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
812 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
813
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
814 \begin{cfuncdesc}{void}{PyErr_Clear}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
815 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
816 is no effect.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
817 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
818
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
819 \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
820 PyObject **ptraceback}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
821 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
822 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
823 \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
824 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
825 \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
826 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
827 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
828 temporarily.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
829 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
830
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
831 \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, PyObject *traceback}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
832 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
833 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
834 \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
835 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
836 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
837 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
838 (Violating these rules will cause subtle problems later.) This call
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
839 takes away a reference to each object, i.e. you must own a reference
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
840 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
841 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
842 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
843 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
844 temporarily.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
845 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
846
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
847 \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
848 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
849 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
850 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
851 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
852 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
853 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
854
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
855 \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
856 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
857 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
858 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
859 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
860
12355
04802b7e8a1f Yet another markup nit: functions that are part of the Python/C API
Fred Drake <fdrake@acm.org>
parents: 12354
diff changeset
861 \begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
04802b7e8a1f Yet another markup nit: functions that are part of the Python/C API
Fred Drake <fdrake@acm.org>
parents: 12354
diff changeset
862 const char *format, ...}
12353
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
863 This function sets the error indicator using a printf-style format
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
864 string. The first argument specifies the exception type and the
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
865 second argument specifies the format string for the exception. Any
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
866 subsequent arguments are converted to output by the C library's
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
867 \cfunction{vsprintf()} function. The buffer used internally by
12355
04802b7e8a1f Yet another markup nit: functions that are part of the Python/C API
Fred Drake <fdrake@acm.org>
parents: 12354
diff changeset
868 \cfunction{PyErr_Format()} is 500 bytes long. The caller is
04802b7e8a1f Yet another markup nit: functions that are part of the Python/C API
Fred Drake <fdrake@acm.org>
parents: 12354
diff changeset
869 responsible for guaranteeing that the formatted output does not
04802b7e8a1f Yet another markup nit: functions that are part of the Python/C API
Fred Drake <fdrake@acm.org>
parents: 12354
diff changeset
870 overflow the buffer.
12353
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
871 \end{cfuncdesc}
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
872
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
873 \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
874 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
875 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
876
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
877 \begin{cfuncdesc}{int}{PyErr_BadArgument}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
878 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
879 \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
880 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
881 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
882
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
883 \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
884 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
885 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
886 \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
887 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
888
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
889 \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
890 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
891 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
892 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
893 \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
894 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
895 then calls
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
896 \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
897 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
898 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
899 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
900 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
901 \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
902 error.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
903 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
904
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
905 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
906 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
907 \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
908 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
909 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
910 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
911
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
912 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
913 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
914 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
915 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
916 \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
917 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
918 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
919 \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
920 \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
921 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
922 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
923 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
924 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
925
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
926 \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
927 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
928 \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
929 \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
930 \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
931 \exception{KeyboardInterrupt} will be raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
932 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
933 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
934
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
935 \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
936 PyObject *base,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
937 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
938 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
939 \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
940 of the form \code{module.class}. The \var{base} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
941 \var{dict} arguments are normally \NULL{}. Normally, this creates a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
942 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
943 name \exception{Exception} (accessible in C as
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
944 \cdata{PyExc_Exception}). In this case the \member{__module__}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
945 attribute of the new class is set to the first part (up to the last
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
946 dot) of the \var{name} argument, and the class name is set to the last
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
947 part (after the last dot). The
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
948 \var{base} argument can be used to specify an alternate base class.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
949 The \var{dict} argument can be used to specify a dictionary of class
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
950 variables and methods.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
951 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
952
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
953
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
954 \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
955
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
956 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
957 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
958 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
959 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
960
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
961 \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
962 \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
963 \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
964 \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
965 \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
966 \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
967 \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
968 \lineiii{PyExc_EOFError}{\exception{EOFError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
969 \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
970 \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
971 \lineiii{PyExc_IOError}{\exception{IOError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
972 \lineiii{PyExc_ImportError}{\exception{ImportError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
973 \lineiii{PyExc_IndexError}{\exception{IndexError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
974 \lineiii{PyExc_KeyError}{\exception{KeyError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
975 \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
976 \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
977 \lineiii{PyExc_NameError}{\exception{NameError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
978 \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
979 \lineiii{PyExc_OSError}{\exception{OSError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
980 \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
981 \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
982 \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
983 \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
984 \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
985 \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
986 \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
987 \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
988 \end{tableiii}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
989
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
990 \noindent
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
991 Note:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
992 \begin{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
993 \item[(1)]
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
994 This is a base class for other standard exceptions. If the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
995 \code{-X} interpreter option is used, these will be tuples
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
996 containing the string exceptions which would have otherwise been
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
997 subclasses.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
998 \end{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
999
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1000
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1001 \section{Deprecation of String Exceptions}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1002
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1003 The \code{-X} command-line option will be removed in Python 1.6. All
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1004 exceptions built into Python or provided in the standard library will
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1005 \withsubitem{(built-in exception)}{\ttindex{Exception}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1006 be classes derived from \exception{Exception}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1007
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1008 String exceptions will still be supported in the interpreter to allow
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1009 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
1010 release.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1011
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1012
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1013 \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
1014
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1015 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
1016 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
1017 values.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1018
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1019 \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
1020
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1021 \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
1022 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
1023 \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
1024 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
1025 \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
1026 the \var{name} pointer is \NULL{} or if the name is equal to one of
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1027 the strings \code{"<stdin>"} or \code{"???"}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1028 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1029
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1030 \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1031 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
1032 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
1033 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
1034 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1035
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1036
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1037 \section{Process Control \label{processControl}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1038
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1039 \begin{cfuncdesc}{void}{Py_FatalError}{char *message}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1040 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
1041 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
1042 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
1043 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
1044 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
1045 \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
1046 produce a \file{core} file.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1047 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1048
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1049 \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
1050 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
1051 \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
1052 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
1053 \code{exit(\var{status})}\ttindex{exit()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1054 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1055
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1056 \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
1057 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
1058 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1059 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
1060 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
1061 functions can be registered.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1062 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
1063 \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
1064 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
1065 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
1066 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
1067 by \var{func}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1068 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1069
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1070
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1071 \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
1072
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1073 \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
1074 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
1075 \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
1076 \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
1077 \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
1078 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
1079 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
1080 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
1081 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
1082 \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
1083 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
1084 \index{package variable!\code{__all__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1085 \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
1086 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
1087 \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
1088 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
1089 \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
1090 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1091
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1092 \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
1093 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
1094 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
1095 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
1096 directly.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1097
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1098 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
1099 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
1100 (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
1101 \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
1102 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
1103 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
1104 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1105
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1106 \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
1107 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
1108 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
1109 \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
1110 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
1111 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
1112 \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
1113 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1114
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1115 \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
1116 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
1117 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
1118 \function{reload()} function calls this function directly. Return a
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1119 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
1120 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
1121 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1122
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1123 \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
1124 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
1125 \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
1126 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
1127 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
1128 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
1129 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
1130 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
1131 import a module.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1132 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
1133 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1134
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1135 \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
1136 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
1137 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
1138 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
1139 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
1140 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
1141 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
1142 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
1143 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1144
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1145 \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
1146 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
1147 \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
1148 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
1149 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
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_GetModuleDict}{}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1153 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
1154 (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
1155 variable.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1156 \end{cfuncdesc}
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 \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
1159 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
1160 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1161
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1162 \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
1163 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
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
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1166 \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
1167 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
1168 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1169
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1170 \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
1171 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
1172 \end{cfuncdesc}
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
1173
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1174 \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
1175 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
1176 \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
1177
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1178 \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1179 Load a frozen module. Return \code{1} for success, \code{0} if the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1180 module is not found, and \code{-1} with an exception set if the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1181 initialization failed. To access the imported module on a successful
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1182 load, use \cfunction{PyImport_ImportModule()}.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1183 (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
1184 already imported.)
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1185 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1186
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1187 \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
1188 This is the structure type definition for frozen module descriptors,
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1189 as generated by the \program{freeze}\index{freeze utility} utility
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1190 (see \file{Tools/freeze/} in the Python source distribution). Its
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1191 definition is:
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1192
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1193 \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
1194 struct _frozen {
6480
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1195 char *name;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1196 unsigned char *code;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1197 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
1198 };
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1199 \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
1200 \end{ctypedesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1201
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1202 \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
1203 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
1204 _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
1205 \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
1206 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
1207 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
1208 \end{cvardesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1209
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1210
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1211 \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
1212
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1213 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
1214 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
1215 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
1216 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
1217
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1218 \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
1219
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1220 \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
1221 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
1222 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
1223 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
1224 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
1225 \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
1226 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1227
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1228 \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
1229 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
1230 \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
1231 \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
1232 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
1233 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1234
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1235 \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
1236 char *attr_name}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1237 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
1238 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
1239 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1240 \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
1241 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1242
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1243
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1244 \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
1245 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
1246 \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
1247 \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
1248 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
1249 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1250
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1251
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1252 \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
1253 PyObject *attr_name}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1254 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
1255 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
1256 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1257 \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
1258 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1259
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1260
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1261 \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
1262 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
1263 \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
1264 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
1265 \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
1266 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1267
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1268
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1269 \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
1270 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
1271 object \var{o},
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1272 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
1273 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
1274 \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
1275 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1276
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1277
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1278 \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
1279 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
1280 \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
1281 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
1282 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1283
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1284
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1285 \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
1286 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
1287 \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
1288 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
1289 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1290
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1291
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1292 \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
1293 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
1294 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
1295 \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
1296 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
1297 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
1298 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1299
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1300
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1301 \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
1302 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
1303 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
1304 \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
1305 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
1306 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
1307 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
1308 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1309
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 \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
1312 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
1313 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
1314 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
1315 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
1316 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
1317 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1318
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1319
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1320 \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
1321 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
1322 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
1323 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
1324 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
1325 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
1326 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1327
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1328
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1329 \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
1330 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
1331 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
1332 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
1333 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1334
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1335
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1336 \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
1337 PyObject *args}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1338 Call a callable Python object \var{callable_object}, with
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1339 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
1340 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
1341 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
1342 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
1343 \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
1344 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1345
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1346 \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
1347 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
1348 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
1349 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
1350 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
1351 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
1352 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
1353 \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
1354 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1355
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1356
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1357 \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
1358 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
1359 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
1360 \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
1361 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
1362 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
1363 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
1364 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
1365 \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
1366 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
1367 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1368
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1369
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1370 \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1371 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
1372 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
1373 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
1374 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1377 \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1378 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
1379 \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
1380 \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
1381 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
1382 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1383
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1384
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1385 \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
1386 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
1387 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
1388 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
1389 \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
1390 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1391
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1392 \begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1393 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
1394 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
1395 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
1396 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
1397 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1400 \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
1401 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
1402 \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
1403 \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
1404 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1405
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1406
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1407 \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
1408 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
1409 Returns \code{-1} on failure. This is the equivalent
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1410 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
1411 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1412
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1413
9931
00fc18ac6aeb Header for PyObject_DelItem() mentioned non-existing 3rd argument.
Guido van Rossum <guido@python.org>
parents: 9476
diff changeset
1414 \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
1415 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
1416 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
1417 \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
1418 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1419
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1420
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1421 \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
1422
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1423 \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1424 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
1425 false otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1426 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
1427 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1428
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1429
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1430 \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
1431 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
1432 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1433 \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
1434 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1435
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1436
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1437 \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
1438 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
1439 \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
1440 \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
1441 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1442
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*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1445 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
1446 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1447 \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
1448 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1449
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1450
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1451 \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
1452 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
1453 failure.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1454 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
1455 \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
1456 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1457
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1458
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1459 \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
1460 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
1461 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
1462 \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
1463 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1464
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1465
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1466 \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
1467 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
1468 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
1469 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
1470 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1471
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1472
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1473 \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
1474 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
1475 \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
1476 \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
1477 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
1478 (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
1479 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1480
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 \begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1483 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
1484 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
1485 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1486
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1487
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1488 \begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1489 Returns \var{o} on success, or \NULL{} on failure.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1490 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
1491 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1492
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1493
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1494 \begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1495 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
1496 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
1497 \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
1498 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1499
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1500
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1501 \begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1502 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
1503 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1504 \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
1505 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1506
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1507
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1508 \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
1509 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
1510 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
1511 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
1512 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1513
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1514
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1515 \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
1516 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
1517 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
1518 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
1519 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1520
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1521
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1522 \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
1523 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
1524 \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
1525 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
1526 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1529 \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
1530 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
1531 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
1532 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
1533 \end{cfuncdesc}
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_Or}{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 \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
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} 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
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
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1541 \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
1542 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
1543 \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
1544 \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
1545 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
1546 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
1547 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
1548 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
1549 \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
1550 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
1551 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
1552 \bifuncindex{coerce}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1553 \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
1554
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1555 \begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1556 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
1557 \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
1558 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
1559 \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
1560
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1561 \begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1562 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
1563 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
1564 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
1565 \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
1566
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1567 \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
1568 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
1569 \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
1570 \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
1571 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1572
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1573
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1574 \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
1575
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1576 \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
1577 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
1578 \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
1579 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1580
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1581 \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
1582 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
1583 \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
1584 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
1585 \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
1586 \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
1587
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1588 \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
1589 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
1590 failure. This is the equivalent of the Python
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1591 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
1592 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1593
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1594
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1595 \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
1596 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
1597 \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
1598 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
1599 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1600
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1601
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1602 \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
1603 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
1604 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
1605 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1606
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1607
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1608 \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
1609 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
1610 \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
1611 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
1612 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1613
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1614
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1615 \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
1616 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
1617 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
1618 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
1619 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1620
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1621 \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
1622 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
1623 \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
1624 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
1625 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1626
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1627 \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
1628 int i2, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1629 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
1630 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
1631 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
1632 \end{cfuncdesc}
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}{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
1635 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
1636 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
1637 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
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*}{PySequence_Tuple}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1641 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
1642 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
1643 \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
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1646 \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
1647 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
1648 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
1649 \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
1650 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
1651 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1652
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1653 \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
1654 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
1655 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
1656 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
1657 \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
1658 \end{cfuncdesc}
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}{int}{PySequence_Index}{PyObject *o, PyObject *value}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1661 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
1662 \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
1663 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
1664 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1665
7493
6857acbe2e74 Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7467
diff changeset
1666
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1667 \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
1668
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1669 \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
1670 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
1671 \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
1672 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1673
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1674
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1675 \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
1676 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
1677 \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
1678 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
1679 \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
1680 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1681
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1682
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1683 \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
1684 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
1685 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1686 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
1687 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1688
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1689
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1690 \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
1691 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
1692 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1693 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
1694 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1695
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1696
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1697 \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
1698 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
1699 \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
1700 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
1701 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
1702 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1703
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1704
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1705 \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
1706 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
1707 \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
1708 \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
1709 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
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*}{PyMapping_Keys}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1714 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
1715 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
1716 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
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}{PyObject*}{PyMapping_Values}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1721 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
1722 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
1723 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
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1727 \begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1728 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
1729 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
1730 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
1731 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
1732 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1733
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1734
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1735 \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
1736 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
1737 \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
1738 \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
1739 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1740
9383
2b34461ba4a3 PyMapping_SetItemString() returns int, not an object.
Guido van Rossum <guido@python.org>
parents: 8881
diff changeset
1741 \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
1742 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
1743 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
1744 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
1745 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1746
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1747
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1748 \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
1749
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1750 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
1751 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
1752 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
1753 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
1754 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
1755 \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
1756 ``family tree'' of Python object types.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1757
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1758
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1759 \section{Fundamental Objects \label{fundamental}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1760
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1761 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
1762 \code{None}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1763
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1764
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1765 \subsection{Type Objects \label{typeObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1766
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1767 \obindex{type}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1768 \begin{ctypedesc}{PyTypeObject}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1769 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
1770 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1771
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1772 \begin{cvardesc}{PyObject*}{PyType_Type}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1773 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
1774 \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
1775 \withsubitem{(in module types)}{\ttindex{TypeType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1776 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1777
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1778 \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
1779 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
1780 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1781
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1782 \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
1783 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
1784 \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
1785 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
1786 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
1787 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1788
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1789
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1790 \subsection{The None Object \label{noneObject}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1791
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1792 \obindex{None@\texttt{None}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1793 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
1794 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
1795 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
1796 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
1797
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1798 \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
1799 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
1800 no methods.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1801 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1802
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1803
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1804 \section{Sequence Objects \label{sequenceObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1805
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1806 \obindex{sequence}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1807 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
1808 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
1809 objects that are intrinsic to the Python language.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1810
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1811
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1812 \subsection{String Objects \label{stringObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1813
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1814 \obindex{string}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1815 \begin{ctypedesc}{PyStringObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
1816 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
1817 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1818
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1819 \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
1820 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
1821 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
1822 layer.\withsubitem{(in module types)}{\ttindex{StringType}}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1823 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1824
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1825 \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
1826 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
1827 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1828
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1829 \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
1830 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
1831 \NULL{} on failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1832 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1833
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1834 \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
1835 int len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1836 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
1837 \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
1838 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
1839 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1840
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1841 \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
1842 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
1843 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1844
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1845 \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
1846 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
1847 checking.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1848 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1849
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1850 \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
1851 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
1852 \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
1853 \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
1854 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
1855 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1856
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1857 \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
1858 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
1859 checking.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1860 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1861
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1862 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1863 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
1864 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
1865 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
1866 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
1867 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
1868 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
1869 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
1870 \NULL{}; the appropriate exception will be set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1871 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1872
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1873 \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1874 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
1875 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
1876 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
1877 the reference count of \var{newpart}.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1878 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1879
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1880 \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
1881 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
1882 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
1883 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
1884 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1885
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1886 \begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1887 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
1888 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
1889 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
1890 a tuple.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1891 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1892
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1893 \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
1894 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
1895 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
1896 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
1897 \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
1898 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
1899 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
1900 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
1901 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
1902 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
1903 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
1904 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1905
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1906 \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
1907 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
1908 \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
1909 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
1910 interned string object with the same value.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1911 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1912
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1913
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1914 \subsection{Unicode Objects \label{unicodeObjects}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1915 \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1916
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1917 %--- Unicode Type -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1918
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1919 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
1920 implementation in Python:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1921
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1922 \begin{ctypedesc}{Py_UNICODE}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1923 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
1924 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
1925 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
1926 \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
1927 native platform compatibility. On all other platforms,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1928 \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
1929 \end{ctypedesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1930
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1931 \begin{ctypedesc}{PyUnicodeObject}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1932 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
1933 \end{ctypedesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1934
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1935 \begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1936 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
1937 \end{cvardesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1938
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1939 %--- 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
1940
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1941 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
1942 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
1943
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1944 \begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1945 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
1946 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1947
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1948 \begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1949 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
1950 PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1951 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1952
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1953 \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
1954 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
1955 a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1956 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1957
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1958 \begin{cfuncdesc}{int}{PyUnicode_AS_UNICODE}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1959 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
1960 has to be a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1961 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1962
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1963 \begin{cfuncdesc}{int}{PyUnicode_AS_DATA}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1964 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
1965 o has to be a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1966 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1967
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1968 % --- Unicode character properties ---------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1969
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1970 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
1971 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
1972 functions depending on the Python configuration.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1973
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1974 \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
1975 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
1976 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1977
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1978 \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
1979 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
1980 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1981
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1982 \begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1983 Returns 1/0 depending on whether \var{ch} is a uppercase character.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1984 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1985
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1986 \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
1987 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
1988 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1989
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1990 \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
1991 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
1992 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1993
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1994 \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
1995 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
1996 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1997
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
1998 \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
1999 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
2000 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2001
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2002 \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
2003 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
2004 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2005
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2006 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
2007
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2008 \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
2009 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
2010 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2011
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2012 \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
2013 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
2014 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2015
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2016 \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
2017 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
2018 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2019
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2020 \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
2021 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
2022 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
2023 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2024
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2025 \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
2026 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
2027 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
2028 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2029
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2030 \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
2031 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
2032 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
2033 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2034
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2035 % --- Plain Py_UNICODE ---------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2036
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2037 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
2038 use these APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2039
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2040 \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
2041 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2042
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2043 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
2044 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
2045 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
2046 The buffer is copied into the new object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2047 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2048
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2049 \begin{cfuncdesc}{Py_UNICODE *}{PyUnicode_AsUnicode}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2050 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
2051 \ctype{Py_UNICODE} buffer.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2052 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2053
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2054 \begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2055 Return the length of the Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2056 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2057
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2058 \begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2059
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2060 Coerce obj to an Unicode object and return a reference with
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2061 incremented refcount.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2062
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2063 Coercion is done in the following way:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2064 \begin{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2065 \item Unicode objects are passed back as-is with incremented
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2066 refcount.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2067
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2068 \item String and other char buffer compatible objects are decoded
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2069 under the assumptions that they contain UTF-8 data. Decoding
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2070 is done in "strict" mode.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2071
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2072 \item All other objects raise an exception.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2073 \end{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2074 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
2075 for decref'ing the returned objects.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2076 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2077
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2078 % --- wchar_t support for platforms which support it ---------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2079
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2080 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
2081 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
2082 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
2083 \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
2084
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2085 \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
2086 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2087 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
2088 given size. Returns \NULL{} on failure.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2089 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2090
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2091 \begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2092 wchar_t *w,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2093 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2094
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2095 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
2096 \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
2097 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
2098 of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2099 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2100
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 \subsubsection{Builtin Codecs \label{builtinCodecs}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2103
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2104 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
2105 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
2106 following functions.
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 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
2109 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
2110 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
2111
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2112 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
2113 is UTF-8.
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 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
2116 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
2117 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
2118
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2119 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
2120 following generic ones are documented for simplicity.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2121
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2122 % --- Generic Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2123
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2124 These are the generic codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2125
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2126 \begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2127 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2128 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2129 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2130
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2131 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
2132 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
2133 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
2134 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
2135 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
2136 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2137 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2138
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2139 \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
2140 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2141 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2142 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2143
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2144 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
2145 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
2146 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
2147 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
2148 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
2149 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2150 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2151
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2152 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2153 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2154 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2155
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2156 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
2157 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
2158 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
2159 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
2160 \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
2161 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2162
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2163 % --- UTF-8 Codecs -------------------------------------------------------
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 These are the UTF-8 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2166
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2167 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2168 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2169 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2170
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2171 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
2172 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
2173 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2174 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2175
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2176 \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
2177 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2178 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2179
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2180 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
2181 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
2182 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2183 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2184
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2185 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
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 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
2188 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2189 \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
2190 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2191
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2192 % --- UTF-16 Codecs ------------------------------------------------------ */
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2193
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2194 These are the UTF-16 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2195
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2196 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2197 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2198 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2199 int *byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2200
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2201 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
2202 returns the corresponding Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2203
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2204 \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
2205 to ``strict''.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2206
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2207 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
2208 the given byte order:
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 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2211 *byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2212 *byteorder == 0: native order
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2213 *byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2214 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2215
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2216 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
2217 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
2218 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
2219 order at the end of input data.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2220
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2221 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
2222
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2223 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
2224 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2225
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2226 \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
2227 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2228 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2229 int byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2230
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2231 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
2232 Unicode data in \var{s}.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2233
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2234 If \var{byteorder} is not 0, output is written according to the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2235 following byte order:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2236
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2237 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2238 byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2239 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
2240 byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2241 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2242
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2243 If byteorder is 0, the output string will always start with the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2244 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
2245 prepended.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2246
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2247 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
2248 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
2249 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
2250
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2251 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
2252 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2253
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2254 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2255
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2256 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
2257 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
2258 ``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
2259 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2260 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2261
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2262 % --- Unicode-Escape Codecs ----------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2263
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2264 These are the ``Unicode Esacpe'' codec APIs:
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 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2267 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2268 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2269
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2270 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
2271 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
2272 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2273 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2274
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2275 \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
2276 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2277 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2278
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2279 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
2280 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
2281 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2282 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2283
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2284 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
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 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
2287 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
2288 \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
2289 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2290
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2291 % --- Raw-Unicode-Escape Codecs ------------------------------------------
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 These are the ``Raw Unicode Esacpe'' codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2294
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2295 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2296 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2297 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2298
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2299 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
2300 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
2301 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2302 \end{cfuncdesc}
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 \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
2305 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2306 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2307
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2308 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
2309 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
2310 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2311 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2312
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2313 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2314
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2315 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
2316 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
2317 \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
2318 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2319
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2320 % --- Latin-1 Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2321
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2322 These are the Latin-1 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2323
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2324 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
2325 are accepted by the codecs during encoding.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2326
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2327 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2328 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2329 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2330
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2331 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
2332 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
2333 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2334 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2335
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2336 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2337 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2338 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2339
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2340 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
2341 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
2342 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 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
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 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
2348 Python string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2349 \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
2350 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2351
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2352 % --- ASCII Codecs -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2353
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2354 These are the ASCII codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2355
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2356 Only 7-bit ASCII data is excepted. All other codes generate errors.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2357
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2358 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2359 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2360 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2361
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2362 Creates a Unicode object by decoding \var{size} bytes of the ASCII
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2363 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
2364 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2365 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2366
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2367 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2368 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2369 const char *errors}
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 Encodes the \ctype{Py_UNICODE} buffer of the given size using ASCII
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2372 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
2373 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2374 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2375
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2376 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2377
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2378 Encodes a Unicode objects using ASCII and returns the result as Python
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2379 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2380 \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
2381 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2382
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2383 % --- Character Map Codecs -----------------------------------------------
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 These are the mapping codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2386
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2387 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
2388 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
2389 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
2390 codec uses mapping to encode and decode characters.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2391
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2392 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
2393 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
2394 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
2395
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2396 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
2397 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
2398 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
2399
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2400 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
2401 interface.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2402
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2403 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
2404 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
2405 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
2406 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
2407 points.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2408
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2409 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2410 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2411 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2412 const char *errors}
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 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
2415 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
2416 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
2417 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2418
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2419 \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
2420 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2421 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2422 const char *errors}
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 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
2425 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
2426 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
2427 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2428
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2429 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2430 PyObject *mapping}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2431
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2432 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
2433 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
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 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
2439
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2440 \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
2441 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2442 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2443 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2444
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2445 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
2446 a character mapping \var{table} to it and returns the resulting
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2447 Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2448
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2449 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
2450 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
2451
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2452 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2453 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
2454 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
2455
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2456 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
2457 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2458
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2459 % --- MBCS codecs for Windows --------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2460
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2461 These are the MBCS codec APIs. They are currently only available
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2462 Windows and use the Win32 MBCS converters to implement the
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2463 conversions.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2464
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2465 Note that MBCS (or DBCS) is a class of encodings, not just one. The
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2466 target encoding is defined by the user settings on the machine running
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2467 the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2468
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2469 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2470 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2471 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2472
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2473 Creates a Unicode object by decoding \var{size} bytes of the MBCS
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2474 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
2475 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2476 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2477
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2478 \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
2479 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2480 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2481
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2482 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
2483 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
2484 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2485 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2486
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2487 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2488
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2489 Encodes a Unicode objects using MBCS and returns the result as Python
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2490 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2491 \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
2492 \end{cfuncdesc}
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 % --- Methods & Slots ----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2495
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2496 \subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2497
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2498 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
2499 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
2500 Unicode objects or integers as apporpriate.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2501
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2502 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
2503
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2504 \begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2505 PyObject *right}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2506
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2507 Concat two strings giving a new Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2508 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2509
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2510 \begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2511 PyObject *sep,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2512 int maxsplit}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2513
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2514 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
2515
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2516 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
2517 substrings. Otherwise, splits occur at the given separator.
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 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
2520
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2521 Separators are not included in the resulting list.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2522 \end{cfuncdesc}
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_Splitlines}{PyObject *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2525 int maxsplit}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2526
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2527 Dito, but split at line breaks.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2528
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2529 CRLF is considered to be one line break. Line breaks are not
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2530 included in the resulting list.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2531 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2532
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2533 \begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2534 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2535 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2536
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2537 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
2538 return the resulting Unicode object.
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 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
2541 integers or None (causing deletion of the character).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2542
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2543 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2544 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
2545 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
2546
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2547 \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
2548 which indicates to use the default error handling.
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 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2551
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2552 \begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2553 PyObject *seq}
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 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
2556 the resulting Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2557 \end{cfuncdesc}
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 \begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2560 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2561 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2562 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2563 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2564
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2565 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
2566 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
2567 \var{direction} == 1 a suffix match), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2568 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2569
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2570 \begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2571 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2572 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2573 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2574 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2575
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2576 Return the first position of \var{substr} in
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2577 \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
2578 (\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
2579 \var{direction} == -1 a backward search), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2580 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2581
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2582 \begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2583 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2584 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2585 int end}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2586
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2587 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
2588 \var{str}[\var{start}:\var{end}]
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2589 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2590
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2591 \begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2592 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2593 PyObject *replstr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2594 int maxcount}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2595
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2596 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
2597 \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
2598 \var{maxcount} == -1 means: replace all occurrences.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2599 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2600
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2601 \begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2602 PyObject *right}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2603
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2604 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
2605 greater than resp.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2606 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2607
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2608 \begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2609 PyObject *args}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2610 Returns a new string object from \var{format} and \var{args}. Analogous
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2611 to \code{\var{format} \% \var{args}}. The \var{args} argument must be
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2612 a tuple.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2613 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2614
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2615 \begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2616 PyObject *element}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2617
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2618 Checks whether \var{element} is contained in \var{container} and
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2619 returns 1/0 accordingly.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2620
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2621 \var{element} has to coerce to an one element Unicode string. -1 is
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2622 returned in case of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2623 \end{cfuncdesc}
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
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2626 \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
2627 \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
2628
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2629 \obindex{buffer}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2630 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
2631 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
2632 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
2633 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
2634 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
2635
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2636 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
2637 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
2638 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
2639 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
2640 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
2641
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2642 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
2643 \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
2644 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
2645 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
2646 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
2647 object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2648
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2649 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
2650 ``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
2651 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
2652
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2653 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
2654 (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
2655 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
2656 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
2657 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
2658 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
2659 interface.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2660
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2661 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
2662 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
2663 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
2664 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
2665 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
2666 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
2667 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
2668 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
2669 format.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2670
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2671 \begin{ctypedesc}{PyBufferObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2672 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
2673 \end{ctypedesc}
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2674
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2675 \begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2676 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
2677 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
2678 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
2679 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2680
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2681 \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
2682 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
2683 \cfunction{PyBuffer_FromObject()} or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2684 \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
2685 \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
2686 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
2687 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
2688 length.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2689 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2690
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2691 \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
2692 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
2693 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2694
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2695 \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
2696 int offset, int size}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2697 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
2698 \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
2699 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
2700 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
2701 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
2702 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
2703 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
2704 \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
2705 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
2706 \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
2707 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2708
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2709 \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
2710 int offset,
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2711 int size}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2712 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
2713 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
2714 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
2715 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
2716 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2717
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2718 \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
2719 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
2720 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
2721 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
2722 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
2723 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
2724 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
2725 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
2726 that case.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2727 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2728
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2729 \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
2730 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
2731 is writable.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2732 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2733
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2734 \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
2735 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
2736 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
2737 \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
2738 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
2739
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
2740
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2741 \subsection{Tuple Objects \label{tupleObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2742
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2743 \obindex{tuple}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2744 \begin{ctypedesc}{PyTupleObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
2745 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
2746 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2747
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2748 \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
2749 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
2750 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
2751 layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2752 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2753
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2754 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2755 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
2756 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2757
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2758 \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
2759 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
2760 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2761
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2762 \begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2763 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
2764 of that tuple.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2765 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2766
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2767 \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
2768 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
2769 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
2770 sets an \exception{IndexError} exception.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2771 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2772
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2773 \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
2774 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
2775 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2776
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2777 \begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyTupleObject *p,
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2778 int low,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2779 int high}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2780 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
2781 \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
2782 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2783
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2784 \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
2785 int pos, PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2786 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
2787 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
2788 \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
2789 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2790
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2791 \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
2792 int pos, PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2793 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
2794 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
2795 \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
2796 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2797
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2798 \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
2799 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
2800 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
2801 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
2802 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
2803 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
2804 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
2805 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
2806 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
2807 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
2808 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
2809 \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
2810 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2811
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2812
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2813 \subsection{List Objects \label{listObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2814
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2815 \obindex{list}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2816 \begin{ctypedesc}{PyListObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
2817 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
2818 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2819
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2820 \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
2821 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
2822 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
2823 \withsubitem{(in module types)}{\ttindex{ListType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2824 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2825
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2826 \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
2827 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
2828 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2829
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2830 \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
2831 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
2832 failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2833 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2834
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2835 \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
2836 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
2837 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
2838 \bifuncindex{len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2839 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2840
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2841 \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
2842 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
2843 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2844
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2845 \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
2846 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
2847 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
2848 sets an \exception{IndexError} exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2849 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2850
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2851 \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
2852 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
2853 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2854
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2855 \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2856 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
2857 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
2858 \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
2859 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2860
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2861 \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
2862 PyObject *o}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2863 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
2864 \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
2865 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2866
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2867 \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
2868 PyObject *item}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
2869 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
2870 \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
2871 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
2872 \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
2873 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2874
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2875 \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
2876 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
2877 \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
2878 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
2879 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2880
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2881 \begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2882 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
2883 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
2884 \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
2885 exception if unsuccessful.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2886 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
2887 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2888
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2889 \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2890 int low, int high,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2891 PyObject *itemlist}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2892 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
2893 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
2894 \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
2895 \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
2896 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2897
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2898 \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
2899 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
2900 \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
2901 \samp{\var{list}.sort()}.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2902 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2903
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2904 \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
2905 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
2906 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
2907 \samp{\var{list}.reverse()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2908 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2909
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2910 \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
2911 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
2912 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
2913 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2914
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2915
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2916 \section{Mapping Objects \label{mapObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2917
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2918 \obindex{mapping}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2919
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2920
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2921 \subsection{Dictionary Objects \label{dictObjects}}
7269
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 \obindex{dictionary}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2924 \begin{ctypedesc}{PyDictObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
2925 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
2926 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2927
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2928 \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
2929 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
2930 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
2931 \code{types.DictionaryType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2932 \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
2933 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2934
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2935 \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
2936 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
2937 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2938
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2939 \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
2940 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
2941 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2942
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2943 \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
2944 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
2945 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2946
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
2947 \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
2948 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
2949 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
2950 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2951
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2952 \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
2953 PyObject *val}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2954 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
2955 \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
2956 raised.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2957 \end{cfuncdesc}
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{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2960 char *key,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2961 PyObject *val}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2962 Inserts \var{value} into the dictionary using \var{key}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
2963 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
2964 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
2965 \ttindex{PyString_FromString()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2966 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2967
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2968 \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
2969 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
2970 \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
2971 raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2972 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2973
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2974 \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
2975 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
2976 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
2977 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2978
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2979 \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
2980 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
2981 \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
2982 \emph{without} setting an exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2983 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2984
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2985 \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
2986 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
2987 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
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*}{PyDict_Items}{PyObject *p}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
2991 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
2992 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
2993 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
2994 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2995
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2996 \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
2997 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
2998 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
2999 \citetitle[../lib/lib.html]{Python Library Reference}).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3000 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3001
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3002 \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
3003 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
3004 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
3005 \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
3006 Reference}).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3007 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3008
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3009 \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
3010 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
3011 \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
3012 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3013
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3014 \begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3015 int ppos,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3016 PyObject **pkey,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3017 PyObject **pvalue}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3018
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3019 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3020
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3021
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3022 \section{Numeric Objects \label{numericObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3023
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3024 \obindex{numeric}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3025
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3026
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3027 \subsection{Plain Integer Objects \label{intObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3028
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3029 \obindex{integer}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3030 \begin{ctypedesc}{PyIntObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3031 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
3032 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3033
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3034 \begin{cvardesc}{PyTypeObject}{PyInt_Type}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3035 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
3036 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
3037 \withsubitem{(in modules types)}{\ttindex{IntType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3038 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3039
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3040 \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
3041 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
3042 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3043
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3044 \begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3045 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
3046
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3047 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
3048 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
3049 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
3050 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
3051 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
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 \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
3055 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
3056 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
3057 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3058
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3059 \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
3060 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
3061 performed.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3062 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3063
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3064 \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
3065 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
3066 (\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
3067 header files).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3068 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3069
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3070
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3071 \subsection{Long Integer Objects \label{longObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3072
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3073 \obindex{long integer}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3074 \begin{ctypedesc}{PyLongObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3075 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
3076 object.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3077 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3078
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3079 \begin{cvardesc}{PyTypeObject}{PyLong_Type}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3080 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
3081 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
3082 \withsubitem{(in modules types)}{\ttindex{LongType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3083 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3084
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3085 \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
3086 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
3087 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3088
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3089 \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
3090 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
3091 failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3092 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3093
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3094 \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
3095 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
3096 long}, or \NULL{} on failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3097 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3098
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3099 \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
3100 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
3101 \var{v}, or \NULL{} on failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3102 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3103
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3104 \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
3105 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
3106 \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
3107 \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
3108 raised.\withsubitem{(built-in exception)}{OverflowError}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3109 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3110
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3111 \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
3112 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
3113 \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
3114 \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
3115 is raised.\withsubitem{(built-in exception)}{OverflowError}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3116 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3117
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3118 \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
3119 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
3120 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3121
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3122 \begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3123 int base}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3124 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
3125 \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
3126 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
3127 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
3128 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
3129 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
3130 \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
3131 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
3132 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
3133 \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
3134 digits, \exception{ValueError} will be raised.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3135 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3136
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3137
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3138 \subsection{Floating Point Objects \label{floatObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3139
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3140 \obindex{floating point}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3141 \begin{ctypedesc}{PyFloatObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3142 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
3143 object.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3144 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3145
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3146 \begin{cvardesc}{PyTypeObject}{PyFloat_Type}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3147 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
3148 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
3149 \withsubitem{(in modules types)}{\ttindex{FloatType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3150 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3151
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3152 \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
3153 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
3154 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
3155
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3156 \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
3157 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
3158 failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3159 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3160
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3161 \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
3162 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
3163 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3164
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3165 \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
3166 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
3167 \var{pyfloat}, but without error checking.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3168 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3169
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3170
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3171 \subsection{Complex Number Objects \label{complexObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3172
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3173 \obindex{complex number}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3174 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
3175 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
3176 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
3177 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
3178 with both.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3179
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3180 \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
3181
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3182 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
3183 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
3184 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
3185 the API.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3186
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3187 \begin{ctypedesc}{Py_complex}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3188 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
3189 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
3190 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
3191 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
3192
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3193 \begin{verbatim}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3194 typedef struct {
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3195 double real;
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3196 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
3197 } Py_complex;
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3198 \end{verbatim}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3199 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3200
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3201 \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
3202 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
3203 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3204 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3205
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3206 \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
3207 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
3208 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3209 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3210
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3211 \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
3212 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
3213 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3214 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3215
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3216 \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
3217 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
3218 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3219 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3220
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3221 \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
3222 Py_complex divisor}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3223 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
3224 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3225 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3226
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3227 \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
3228 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
3229 \ctype{Py_complex} representation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3230 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3231
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3232
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3233 \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
3234
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3235 \begin{ctypedesc}{PyComplexObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3236 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
3237 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3238
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3239 \begin{cvardesc}{PyTypeObject}{PyComplex_Type}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3240 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
3241 number type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3242 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3243
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3244 \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
3245 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
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}{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
3249 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
3250 \ctype{Py_complex} value.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3251 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3252
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3253 \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
3254 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
3255 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3256
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3257 \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
3258 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
3259 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
3260
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3261 \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
3262 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
3263 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3264
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3265 \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
3266 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
3267 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3268
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3270
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3271 \section{Other Objects \label{otherObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3272
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3273 \subsection{File Objects \label{fileObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3274
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3275 \obindex{file}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3276 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
3277 \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
3278 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
3279
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3280 \begin{ctypedesc}{PyFileObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3281 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
3282 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3283
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3284 \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
3285 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
3286 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
3287 \withsubitem{(in module types)}{\ttindex{FileType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3288 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3289
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3290 \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
3291 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
3292 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3293
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3294 \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
3295 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
3296 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
3297 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
3298 \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
3299 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3300
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3301 \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
3302 char *name, char *mode,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3303 int (*close)(FILE*)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3304 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
3305 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
3306 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
3307 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3308
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3309 \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
3310 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
3311 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3312
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3313 \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
3314 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
3315 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
3316 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
3317 \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
3318 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
3319 \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
3320 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
3321 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
3322 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
3323 \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
3324 immediately.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3325 \withsubitem{(built-in exception)}{\ttindex{EOFError}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3326 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3327
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3328 \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
3329 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
3330 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3331
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3332 \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
3333 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
3334 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
3335 creation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3336 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3337
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3338 \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
3339 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
3340 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
3341 \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
3342 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
3343 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
3344 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
3345 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
3346 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
3347 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
3348 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
3349 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3350
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3351 \begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3352 int flags}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3353 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
3354 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
3355 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
3356 \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
3357 failure; the appropriate exception will be set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3358 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3359
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3360 \begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3361 int flags}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3362 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
3363 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
3364 set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3365 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3366
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3367
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3368 \subsection{Module Objects \label{moduleObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3369
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3370 \obindex{module}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3371 There are only a few functions special to module objects.
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3372
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3373 \begin{cvardesc}{PyTypeObject}{PyModule_Type}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3374 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
3375 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
3376 \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
3377 \end{cvardesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3378
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3379 \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
3380 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
3381 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3382
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3383 \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
3384 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
3385 \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
3386 \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
3387 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
3388 \withsubitem{(module attribute)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3389 \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
3390 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3391
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3392 \begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3393 Return the dictionary object that implements \var{module}'s namespace;
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3394 this object is the same as the \member{__dict__} attribute of the
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3395 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
3396 \withsubitem{(module attribute)}{\ttindex{__dict__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3397 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3398
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3399 \begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3400 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
3401 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
3402 raised and \NULL{} is returned.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3403 \withsubitem{(module attribute)}{\ttindex{__name__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3404 \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
3405 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3406
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3407 \begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3408 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
3409 \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
3410 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
3411 \NULL.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3412 \withsubitem{(module attribute)}{\ttindex{__file__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3413 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3414 \end{cfuncdesc}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3415
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3416
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3417 \subsection{CObjects \label{cObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3418
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3419 \obindex{CObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3420 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
3421 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
3422 information on using these objects.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3423
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3424
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3425 \begin{ctypedesc}{PyCObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3426 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
3427 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
3428 \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
3429 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
3430 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
3431 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
3432 \end{ctypedesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3433
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3434 \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
3435 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
3436 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3437
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3438 \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
3439 void (*destr)(void *)}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3440 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
3441 \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
3442 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
3443 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3444
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3445 \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
3446 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
3447 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
3448 \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
3449 \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
3450 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
3451 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3452
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3453 \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
3454 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
3455 \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
3456 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3457
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3458 \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
3459 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
3460 \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
3461 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3462
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3463
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3464 \chapter{Initialization, Finalization, and Threads
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3465 \label{initialization}}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3466
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3467 \begin{cfuncdesc}{void}{Py_Initialize}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3468 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
3469 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
3470 functions; with the exception of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3471 \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
3472 \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
3473 \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
3474 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
3475 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
3476 \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
3477 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
3478 \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
3479 \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
3480 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
3481 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
3482 \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
3483 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
3484 \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
3485 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
3486 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
3487
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
3488 \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
3489 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
3490 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
3491 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
3492 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3493 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3494
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3495 \begin{cfuncdesc}{void}{Py_Finalize}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3496 Undo all initializations made by \cfunction{Py_Initialize()} and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3497 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
3498 sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3499 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
3500 \cfunction{Py_Initialize()}. Ideally, this frees all memory allocated
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3501 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
3502 time (without calling \cfunction{Py_Initialize()} again first). There
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3503 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
3504
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3505 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
3506 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
3507 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
3508 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
3509 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
3510 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
3511 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
3512
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3513 \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
3514 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
3515 (\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
3516 (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
3517 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
3518 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
3519 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
3520 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
3521 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
3522 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
3523 calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3524 than once.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3525 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3526
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3527 \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
3528 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
3529 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
3530 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
3531 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
3532 \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
3533 \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
3534 \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
3535 (\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
3536 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
3537 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
3538 \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
3539 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
3540 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3541 \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
3542
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3543 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
3544 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
3545 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
3546 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
3547 \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
3548 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
3549 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
3550 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
3551 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
3552 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
3553
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3554 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
3555 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
3556 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
3557 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
3558 (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
3559 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
3560 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
3561 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
3562 re-initialized by calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3563 \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
3564 \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
3565 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
3566 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3567
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3568 \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
3569 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
3570 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
3571 \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
3572 \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
3573 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
3574 (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
3575 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
3576 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
3577 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
3578 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
3579 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
3580 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
3581 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
3582 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
3583 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
3584 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3585
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3586 \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
3587 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
3588 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
3589 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
3590 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
3591 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
3592 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
3593 \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
3594 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
3595 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3596
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3597 \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
3598 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
3599 \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
3600 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
3601 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
3602 \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
3603 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
3604 functions below to find the Python run-time libraries relative to the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3605 interpreter executable. The default value is \code{"python"}. The
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3606 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
3607 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
3608 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
3609 the contents of this storage.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3610 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3611
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3612 \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
3613 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
3614 \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
3615 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
3616 should not modify its value.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3617 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3618
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3619 \begin{cfuncdesc}{char*}{Py_GetPrefix}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3620 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
3621 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
3622 set with \cfunction{Py_SetProgramName()} and some environment variables;
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3623 for example, if the program name is \code{"/usr/local/bin/python"},
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3624 the prefix is \code{"/usr/local"}. The returned string points into
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3625 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
3626 corresponds to the \makevar{prefix} variable in the top-level
11453
a05a05602902 Missed a couple of program options that had been marked by \code.
Fred Drake <fdrake@acm.org>
parents: 11451
diff changeset
3627 \file{Makefile} and the \programopt{-}\programopt{-prefix} argument to the
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3628 \program{configure} script at build time. The value is available to
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
3629 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
3630 also the next function.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3631 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3632
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3633 \begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3634 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
3635 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
3636 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
3637 variables; for example, if the program name is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3638 \code{"/usr/local/bin/python"}, the exec-prefix is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3639 \code{"/usr/local"}. 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
3640 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
3641 \makevar{exec_prefix} variable in the top-level \file{Makefile} and the
11453
a05a05602902 Missed a couple of program options that had been marked by \code.
Fred Drake <fdrake@acm.org>
parents: 11451
diff changeset
3642 \programopt{-}\programopt{-exec_prefix} argument to the
a05a05602902 Missed a couple of program options that had been marked by \code.
Fred Drake <fdrake@acm.org>
parents: 11451
diff changeset
3643 \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
3644 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
3645
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3646 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
3647 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
3648 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
3649 platform dependent files may be installed in the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3650 \code{"/usr/local/plat"} subtree while platform independent may be
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3651 installed in \code{"/usr/local"}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3652
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3653 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
3654 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
3655 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
3656 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
3657 Linux are yet another platform. Different major revisions of the same
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
3658 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
3659 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
3660 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
3661 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
3662 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
3663 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
3664
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3665 System administrators will know how to configure the \program{mount} or
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3666 \program{automount} programs to share \code{"/usr/local"} between platforms
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3667 while having \code{"/usr/local/plat"} be a different filesystem for each
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3668 platform.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3669 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3670
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3671 \begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3672 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
3673 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
3674 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
3675 \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
3676 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
3677 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
3678 \code{sys.executable}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3679 \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
3680 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3681
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3682 \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
3683 \indexiii{module}{search}{path}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3684 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
3685 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
3686 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
3687 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
3688 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
3689 DOS/Windows, and \character{\e n} (the \ASCII{} newline character) on
7271
0061d3916ae4 "ASCII" --> "\ASCII{}"
Fred Drake <fdrake@acm.org>
parents: 7269
diff changeset
3690 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
3691 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
3692 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
3693 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
3694 modules.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3695
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3696 % XXX should give the exact rules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3697 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3698
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3699 \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
3700 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
3701 looks something like
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3702
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
3703 \begin{verbatim}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3704 "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
3705 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3706
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3707 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
3708 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
3709 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
3710 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
3711 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
3712 \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
3713 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3714
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3715 \begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
3716 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
3717 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
3718 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
3719 for Solaris 2.x, which is also known as SunOS 5.x, the value is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3720 \code{"sunos5"}. On Macintosh, it is \code{"mac"}. On Windows, it
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3721 is \code{"win"}. 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
3722 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
3723 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
3724 \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
3725 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3726
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3727 \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
3728 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
3729 for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3730
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3731 \code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3732
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3733 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
3734 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
3735 \code{sys.copyright}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3736 \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
3737 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3738
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3739 \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
3740 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
3741 version, in square brackets, for example:
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3742
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3743 \begin{verbatim}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3744 "[GCC 2.7.2.2]"
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3745 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3746
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3747 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
3748 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
3749 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
3750 \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
3751 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3752
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3753 \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
3754 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
3755 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
3756
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
3757 \begin{verbatim}
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
3758 "#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
3759 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3760
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3761 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
3762 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
3763 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
3764 \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
3765 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3766
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3767 \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
3768 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
3769 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
3770 \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
3771 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
3772 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
3773 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
3774 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
3775 condition is signalled using
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3776 \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
3777 \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
3778 % 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
3779 % check w/ Guido.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3780 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3781
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3782 % 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
3783
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3784 \section{Thread State and the Global Interpreter Lock
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3785 \label{threads}}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3786
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3787 \index{global interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3788 \index{interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3789 \index{lock, interpreter}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3790
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3791 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
3792 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
3793 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
3794 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
3795 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
3796 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
3797 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
3798
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3799 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
3800 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
3801 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
3802 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
3803 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
3804 \withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3805 \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
3806 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
3807 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
3808 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
3809
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3810 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
3811 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
3812 \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
3813 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
3814 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
3815 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
3816 \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
3817 \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
3818 current thread.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3819
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3820 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
3821 \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
3822 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
3823 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
3824 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
3825 manipulated explicitly.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3826
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3827 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
3828 interpreter lock has the following simple structure:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3829
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
3830 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3831 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
3832 Release the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3833 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3834 Reacquire the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3835 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
3836 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3837
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3838 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
3839
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
3840 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3841 Py_BEGIN_ALLOW_THREADS
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3842 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3843 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
3844 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3845
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3846 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
3847 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
3848 \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
3849 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
3850 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
3851 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
3852
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3853 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
3854 following code:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3855
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
3856 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3857 PyThreadState *_save;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3858
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3859 _save = PyEval_SaveThread();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3860 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3861 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
3862 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3863
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3864 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
3865 as follows:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3866
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
3867 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3868 PyThreadState *_save;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3869
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3870 _save = PyThreadState_Swap(NULL);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3871 PyEval_ReleaseLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3872 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3873 PyEval_AcquireLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3874 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
3875 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3876
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3877 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
3878 \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
3879 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
3880 \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
3881 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
3882 is disabled,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3883 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3884 \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
3885 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
3886 \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
3887 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
3888 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
3889 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
3890
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3891 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
3892 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
3893 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
3894 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
3895 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
3896 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
3897 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
3898
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3899 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
3900 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
3901 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
3902 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
3903 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
3904 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
3905 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
3906 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
3907 structure.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3908
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3909 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
3910 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
3911 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
3912 interpreter, for example the module administration
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3913 (\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
3914 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
3915 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
3916 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
3917 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
3918 thread after Python is initialized).
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3919
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3920
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3921 \begin{ctypedesc}{PyInterpreterState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3922 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
3923 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
3924 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
3925 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
3926
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3927 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
3928 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
3929 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
3930 regardless of to which interpreter they belong.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3931 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3932
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3933 \begin{ctypedesc}{PyThreadState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3934 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
3935 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
3936 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
3937 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3938
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3939 \begin{cfuncdesc}{void}{PyEval_InitThreads}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3940 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
3941 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
3942 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
3943 \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
3944 \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
3945 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
3946 \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
3947 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3948
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3949 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
3950 this function before calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3951 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3952
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3953 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
3954 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
3955 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
3956 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
3957 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
3958 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
3959 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
3960 \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
3961 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
3962 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
3963 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
3964 has acquired it.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3965
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3966 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
3967 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
3968
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3969 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
3970 compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3971 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3972
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3973 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3974 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
3975 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
3976 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
3977 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3978 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3979
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3980 \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
3981 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
3982 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
3983 disabled at compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3984 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3985
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3986 \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
3987 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
3988 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
3989 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
3990 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
3991 is disabled at compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3992 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3993
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
3994 \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
3995 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
3996 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
3997 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
3998 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
3999 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
4000 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
4001 time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4002 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4003
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4004 \begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4005 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
4006 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
4007 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
4008 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
4009 (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
4010 compile time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4011 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4012
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4013 \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4014 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
4015 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
4016 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
4017 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
4018 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
4019 time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4020 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4021
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4022 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
4023 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
4024
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4025 \begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4026 This macro expands to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4027 \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4028 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
4029 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
4030 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
4031 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4032 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4033
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4034 \begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4035 This macro expands to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4036 \samp{PyEval_RestoreThread(_save); \}}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4037 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
4038 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
4039 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
4040 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4041 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4042
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4043 \begin{csimplemacrodesc}{Py_BEGIN_BLOCK_THREADS}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4044 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
4045 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
4046 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
4047 time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4048 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4049
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4050 \begin{csimplemacrodesc}{Py_BEGIN_UNBLOCK_THREADS}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4051 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
4052 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
4053 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
4054 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4055 \end{csimplemacrodesc}
6390
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 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
4058 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
4059 interpreter lock has been created.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4060
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4061 \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
4062 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
4063 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
4064 function.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4065 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4066
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4067 \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4068 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
4069 lock must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4070 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4071
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4072 \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4073 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
4074 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
4075 call to \cfunction{PyInterpreterState_Clear()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4076 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4077
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4078 \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
4079 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
4080 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
4081 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
4082 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4083
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4084 \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4085 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
4086 must be held.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4087 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4088
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4089 \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4090 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
4091 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
4092 call to \cfunction{PyThreadState_Clear()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4093 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4094
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4095 \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4096 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
4097 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
4098 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
4099 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4100
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4101 \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
4102 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
4103 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
4104 must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4105 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4106
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4107
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4108 \chapter{Memory Management \label{memory}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4109 \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
4110
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4111
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4112 \section{Overview \label{memoryOverview}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4113
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4114 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
4115 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
4116 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
4117 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
4118 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
4119 preallocation or caching.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4120
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4121 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
4122 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
4123 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
4124 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
4125 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
4126 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
4127 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
4128 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
4129 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
4130 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
4131 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
4132 the private heap.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4133
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4134 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
4135 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
4136 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
4137 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
4138 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
4139 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
4140 this document.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4141
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4142 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
4143 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
4144 library: \cfunction{malloc()}\ttindex{malloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4145 \cfunction{calloc()}\ttindex{calloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4146 \cfunction{realloc()}\ttindex{realloc()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4147 \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
4148 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
4149 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
4150 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
4151 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
4152 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
4153
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4154 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4155 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4156 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
4157
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4158 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4159 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4160 ...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
4161 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4162 free(buf); /* malloc'ed */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4163 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4164 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4165
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4166 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
4167 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
4168 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
4169
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4170 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
4171 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
4172 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
4173 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
4174 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
4175 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
4176 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
4177 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
4178 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
4179 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
4180 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
4181 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
4182 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
4183 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
4184 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
4185
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 \section{Memory Interface \label{memoryInterface}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4188
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4189 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
4190 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
4191
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4192
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4193 \begin{ctypedesc}{ANY*}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4194 The type used to represent arbitrary blocks of memory. Values of this
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4195 type should be cast to the specific type that is needed.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4196 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4197
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4198 \begin{cfuncdesc}{ANY*}{PyMem_Malloc}{size_t n}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4199 Allocates \var{n} bytes and returns a pointer of type \ctype{ANY*} to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4200 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
4201 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
4202 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4203
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4204 \begin{cfuncdesc}{ANY*}{PyMem_Realloc}{ANY *p, size_t n}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4205 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
4206 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
4207 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
4208 \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
4209 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
4210 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
4211 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
4212 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4213
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4214 \begin{cfuncdesc}{void}{PyMem_Free}{ANY *p}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4215 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
4216 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
4217 \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
4218 \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
4219 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
4220 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4221
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4222 \begin{cfuncdesc}{ANY*}{Py_Malloc}{size_t n}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4223 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
4224 \cfunction{PyErr_NoMemory()} on failure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4225 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4226
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4227 \begin{cfuncdesc}{ANY*}{Py_Realloc}{ANY *p, size_t n}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4228 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
4229 \cfunction{PyErr_NoMemory()} on failure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4230 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4231
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4232 \begin{cfuncdesc}{void}{Py_Free}{ANY *p}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4233 Same as \cfunction{PyMem_Free()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4234 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4235
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4236 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
4237 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
4238
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4239 \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
4240 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
4241 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
4242 \ctype{\var{TYPE}*}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4243 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4244
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4245 \begin{cfuncdesc}{\var{TYPE}*}{PyMem_RESIZE}{ANY *p, TYPE, size_t n}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4246 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
4247 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
4248 cast to \ctype{\var{TYPE}*}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4249 \end{cfuncdesc}
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 \begin{cfuncdesc}{void}{PyMem_DEL}{ANY *p}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4252 Same as \cfunction{PyMem_Free()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4253 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4254
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4255
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4256 \section{Examples \label{memoryExamples}}
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 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
4259 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
4260 first function set:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4261
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4262 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4263 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4264 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
4265
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4266 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4267 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4268 /* ...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
4269 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4270 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
4271 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4272 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4273
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4274 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
4275 \cfunction{PyErr_NoMemory()} is obviated:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4276
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4277 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4278 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4279 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
4280
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4281 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4282 return NULL;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4283 /* ...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
4284 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4285 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
4286 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4287 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4288
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4289 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
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 = 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
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 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
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 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
4304 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
4305 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
4306 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
4307 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
4308 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
4309 allocators operating on different heaps.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4310
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4311 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4312 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
4313 char *buf2 = (char *) malloc(BUFSIZ);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4314 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
4315 ...
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4316 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
4317 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
4318 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
4319 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4320
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4321 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
4322 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
4323 \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
4324 \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
4325 their corresponding macros
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4326 \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
4327 \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
4328
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4329 % XXX use this for Python 1.6:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4330 % \cfunction{_PyObject_New()}, \cfunction{_PyObject_NewVar()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4331 % \cfunction{_PyObject_Del()}, or with their corresponding macros
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4332 % \cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4333 % \cfunction{PyObject_DEL()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4334
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4335 % These will be explained in the next chapter on defining and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4336 % implementing new object types in C.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4337
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4338
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4339 \chapter{Defining New Object Types \label{newTypes}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4340
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4341 \begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4342 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4343
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4344 \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
4345 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4346
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4347 \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
4348 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4349
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4350 \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
4351 int size}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4352 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4353
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
4354 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
4355
5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes.
Guido van Rossum <guido@python.org>
parents: 8029
diff changeset
4356 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
4357
5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes.
Guido van Rossum <guido@python.org>
parents: 8029
diff changeset
4358 Py_BuildValue
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4359
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4360 DL_IMPORT
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4361
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4362 Py*_Check
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4363
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4364 _Py_NoneStruct
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4365
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4366
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4367 \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
4368
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4369 PyObject, PyVarObject
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4370
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4371 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
4372
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4373 Typedefs:
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4374 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
4375 intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4376 destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4377 setattrofunc, cmpfunc, reprfunc, hashfunc
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
4378
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4379
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4380 \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
4381
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4382 \begin{ctypedesc}{PyMappingMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4383 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
4384 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
4385 \end{ctypedesc}
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{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
4389
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4390 \begin{ctypedesc}{PyNumberMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4391 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
4392 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
4393 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4394
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4395
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4396 \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
4397
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4398 \begin{ctypedesc}{PySequenceMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4399 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
4400 to implement the sequence protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4401 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4402
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4403
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4404 \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
4405 \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
4406
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4407 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
4408 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
4409 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
4410 \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
4411
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4412 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
4413 \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
4414 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
4415 a \ctype{PyBufferProcs} structure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4416
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4417 \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
4418 \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
4419 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
4420 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
4421 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
4422 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
4423 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
4424
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4425 \begin{ctypedesc}{PyBufferProcs}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4426 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
4427 implementation of the buffer protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4428
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4429 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
4430 \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
4431 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
4432 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
4433 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
4434
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4435 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
4436 \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
4437 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
4438
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4439 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
4440 \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
4441 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
4442 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
4443 \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
4444
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4445 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
4446 \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
4447 \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
4448 \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
4449 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
4450 \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
4451 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
4452 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
4453 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
4454 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
4455 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
4456 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
4457 \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
4458 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
4459 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
4460 have character-based content.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4461
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4462 \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
4463 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
4464 \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
4465 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4466
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4467 \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
4468 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
4469 \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
4470 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
4471 \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
4472 \end{datadesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4473
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4474 \begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4475 (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
4476 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
4477 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
4478 \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
4479 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
4480 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
4481 \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
4482 memory.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4483 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4484
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4485 \begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4486 (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
4487 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
4488 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
4489 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
4490 \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
4491 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
4492 \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
4493 % 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
4494 % 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
4495 % 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
4496 % code.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
4497 \end{ctypedesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
4498
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4499 \begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4500 (PyObject *self, int *lenp)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4501 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
4502 \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
4503 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
4504 The function cannot fail.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4505 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4506
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4507 \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4508 (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
4509 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4510
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4511
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4512 % \chapter{Debugging \label{debugging}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4513 %
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4514 % 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
4515
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
4516
7708
4991aaab17bd Revert the index stuff to work better with LaTeX2HTML.
Fred Drake <fdrake@acm.org>
parents: 7620
diff changeset
4517 \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
4518
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
4519 \end{document}