Mercurial > cpython-lru_cache-weakref

annotate Doc/api/api.tex @ 18830:fdb388f2df4e legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Don't "import *" from stat at all -- just import what's needed, and do it back in copy_file() (not at module level).
author Greg Ward <gward@python.net>
date Wed, 25 Jul 2001 19:48:03 +0000
parents b465cd50cf36
children a0819708fe9c
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
15953
8349b4dfc51a Undoing the whitespace patches which sneaked into the earlier patch.
Marc-André Lemburg <mal@egenix.com>
parents: 15952
diff changeset
7 \makeindex % tell \index to actually write the .idx file
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
8
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
9
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 \begin{document}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
11
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 \maketitle
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
13
8782
ae3e2eaef9b9 Update to use a separate page for front matter.
Fred Drake <fdrake@acm.org>
parents: 8138
diff changeset
14 \ifhtml
ae3e2eaef9b9 Update to use a separate page for front matter.
Fred Drake <fdrake@acm.org>
parents: 8138
diff changeset
15 \chapter*{Front Matter\label{front}}
ae3e2eaef9b9 Update to use a separate page for front matter.
Fred Drake <fdrake@acm.org>
parents: 8138
diff changeset
16 \fi
ae3e2eaef9b9 Update to use a separate page for front matter.
Fred Drake <fdrake@acm.org>
parents: 8138
diff changeset
17
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 \input{copyright}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
19
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
20 \begin{abstract}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
21
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 \noindent
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
23 This manual documents the API used by C and \Cpp{} programmers who
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
24 want to write extension modules or embed Python. It is a companion to
11451
38c7444f633a Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11222
diff changeset
25 \citetitle[../ext/ext.html]{Extending and Embedding the Python
38c7444f633a Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11222
diff changeset
26 Interpreter}, which describes the general principles of extension
38c7444f633a Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11222
diff changeset
27 writing but does not document the API functions in detail.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
29 \strong{Warning:} The current version of this document is incomplete.
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
30 I hope that it is nevertheless useful. I will continue to work on it,
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
31 and release new versions from time to time, independent from Python
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
32 source code releases.
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
33
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 \end{abstract}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
35
7092
8a55643e667f Removed \mytableofcontents; just use \tableofcontents.
Fred Drake <fdrake@acm.org>
parents: 7081
diff changeset
36 \tableofcontents
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
37
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
38 % XXX Consider moving all this back to ext.tex and giving api.tex
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
39 % XXX a *really* short intro only.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
40
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
41 \chapter{Introduction \label{intro}}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
42
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
43 The Application Programmer's Interface to Python gives C and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
44 \Cpp{} programmers access to the Python interpreter at a variety of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
45 levels. The API is equally usable from \Cpp{}, but for brevity it is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
46 generally referred to as the Python/C API. There are two
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
47 fundamentally different reasons for using the Python/C API. The first
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
48 reason is to write \emph{extension modules} for specific purposes;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
49 these are C modules that extend the Python interpreter. This is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
50 probably the most common use. The second reason is to use Python as a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
51 component in a larger application; this technique is generally
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
52 referred to as \dfn{embedding} Python in an application.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
53
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
54 Writing an extension module is a relatively well-understood process,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
55 where a ``cookbook'' approach works well. There are several tools
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
56 that automate the process to some extent. While people have embedded
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
57 Python in other applications since its early existence, the process of
17875
151a2fa296fe Typo: "that" --> "than"
Fred Drake <fdrake@acm.org>
parents: 17835
diff changeset
58 embedding Python is less straightforward than writing an extension.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
59
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
60 Many API functions are useful independent of whether you're embedding
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
61 or extending Python; moreover, most applications that embed Python
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
62 will need to provide a custom extension as well, so it's probably a
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
63 good idea to become familiar with writing an extension before
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
64 attempting to embed Python in a real application.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
65
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
66
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
67 \section{Include Files \label{includes}}
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
68
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
69 All function, type and macro definitions needed to use the Python/C
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
70 API are included in your code by the following line:
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
71
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
72 \begin{verbatim}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
73 #include "Python.h"
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
74 \end{verbatim}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
75
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
76 This implies inclusion of the following standard headers:
14870
e35a3a772dca Note that including Python.h includes limits.h when available.
Fred Drake <fdrake@acm.org>
parents: 14782
diff changeset
77 \code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>},
e35a3a772dca Note that including Python.h includes limits.h when available.
Fred Drake <fdrake@acm.org>
parents: 14782
diff changeset
78 \code{<limits.h>}, and \code{<stdlib.h>} (if available).
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
79
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
80 All user visible names defined by Python.h (except those defined by
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
81 the included standard headers) have one of the prefixes \samp{Py} or
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
82 \samp{_Py}. Names beginning with \samp{_Py} are for internal use by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
83 the Python implementation and should not be used by extension writers.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
84 Structure member names do not have a reserved prefix.
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
85
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
86 \strong{Important:} user code should never define names that begin
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
87 with \samp{Py} or \samp{_Py}. This confuses the reader, and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
88 jeopardizes the portability of the user code to future Python
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
89 versions, which may define additional names beginning with one of
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
90 these prefixes.
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
91
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
92 The header files are typically installed with Python. On \UNIX, these
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
93 are located in the directories
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
94 \file{\envvar{prefix}/include/python\var{version}/} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
95 \file{\envvar{exec_prefix}/include/python\var{version}/}, where
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
96 \envvar{prefix} and \envvar{exec_prefix} are defined by the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
97 corresponding parameters to Python's \program{configure} script and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
98 \var{version} is \code{sys.version[:3]}. On Windows, the headers are
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
99 installed in \file{\envvar{prefix}/include}, where \envvar{prefix} is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
100 the installation directory specified to the installer.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
101
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
102 To include the headers, place both directories (if different) on your
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
103 compiler's search path for includes. Do \emph{not} place the parent
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
104 directories on the search path and then use
14557
a71385f8b4da Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents: 14553
diff changeset
105 \samp{\#include <python\shortversion/Python.h>}; this will break on
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
106 multi-platform builds since the platform independent headers under
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
107 \envvar{prefix} include the platform specific headers from
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
108 \envvar{exec_prefix}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
109
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
110 \Cpp{} users should note that though the API is defined entirely using
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
111 C, the header files do properly declare the entry points to be
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
112 \code{extern "C"}, so there is no need to do anything special to use
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
113 the API from \Cpp.
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
114
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
115
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
116 \section{Objects, Types and Reference Counts \label{objects}}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
117
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
118 Most Python/C API functions have one or more arguments as well as a
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
119 return value of type \ctype{PyObject*}. This type is a pointer
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
120 to an opaque data type representing an arbitrary Python
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
121 object. Since all Python object types are treated the same way by the
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
122 Python language in most situations (e.g., assignments, scope rules,
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
123 and argument passing), it is only fitting that they should be
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
124 represented by a single C type. Almost all Python objects live on the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
125 heap: you never declare an automatic or static variable of type
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
126 \ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
127 be declared. The sole exception are the type objects\obindex{type};
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
128 since these must never be deallocated, they are typically static
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
129 \ctype{PyTypeObject} objects.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
130
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
131 All Python objects (even Python integers) have a \dfn{type} and a
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
132 \dfn{reference count}. An object's type determines what kind of object
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
133 it is (e.g., an integer, a list, or a user-defined function; there are
11451
38c7444f633a Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11222
diff changeset
134 many more as explained in the \citetitle[../ref/ref.html]{Python
38c7444f633a Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11222
diff changeset
135 Reference Manual}). For each of the well-known types there is a macro
38c7444f633a Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents: 11222
diff changeset
136 to check whether an object is of that type; for instance,
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
137 \samp{PyList_Check(\var{a})} is true if (and only if) the object
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
138 pointed to by \var{a} is a Python list.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
139
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
140
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
141 \subsection{Reference Counts \label{refcounts}}
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
142
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
143 The reference count is important because today's computers have a
8029
95142c8a09c8 Typo: (and often severly limited) -- severely
Fred Drake <fdrake@acm.org>
parents: 8021
diff changeset
144 finite (and often severely limited) memory size; it counts how many
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
145 different places there are that have a reference to an object. Such a
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
146 place could be another object, or a global (or static) C variable, or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
147 a local variable in some C function. When an object's reference count
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
148 becomes zero, the object is deallocated. If it contains references to
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
149 other objects, their reference count is decremented. Those other
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
150 objects may be deallocated in turn, if this decrement makes their
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
151 reference count become zero, and so on. (There's an obvious problem
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
152 with objects that reference each other here; for now, the solution is
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
153 ``don't do that.'')
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
154
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
155 Reference counts are always manipulated explicitly. The normal way is
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
156 to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
157 increment an object's reference count by one, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
158 \cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
159 one. The \cfunction{Py_DECREF()} macro is considerably more complex
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
160 than the incref one, since it must check whether the reference count
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
161 becomes zero and then cause the object's deallocator to be called.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
162 The deallocator is a function pointer contained in the object's type
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
163 structure. The type-specific deallocator takes care of decrementing
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
164 the reference counts for other objects contained in the object if this
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
165 is a compound object type, such as a list, as well as performing any
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
166 additional finalization that's needed. There's no chance that the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
167 reference count can overflow; at least as many bits are used to hold
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
168 the reference count as there are distinct memory locations in virtual
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
169 memory (assuming \code{sizeof(long) >= sizeof(char*)}). Thus, the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
170 reference count increment is a simple operation.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
171
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
172 It is not necessary to increment an object's reference count for every
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
173 local variable that contains a pointer to an object. In theory, the
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
174 object's reference count goes up by one when the variable is made to
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
175 point to it and it goes down by one when the variable goes out of
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
176 scope. However, these two cancel each other out, so at the end the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
177 reference count hasn't changed. The only real reason to use the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
178 reference count is to prevent the object from being deallocated as
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
179 long as our variable is pointing to it. If we know that there is at
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
180 least one other reference to the object that lives at least as long as
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
181 our variable, there is no need to increment the reference count
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
182 temporarily. An important situation where this arises is in objects
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
183 that are passed as arguments to C functions in an extension module
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
184 that are called from Python; the call mechanism guarantees to hold a
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
185 reference to every argument for the duration of the call.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
186
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
187 However, a common pitfall is to extract an object from a list and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
188 hold on to it for a while without incrementing its reference count.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
189 Some other operation might conceivably remove the object from the
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
190 list, decrementing its reference count and possible deallocating it.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
191 The real danger is that innocent-looking operations may invoke
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
192 arbitrary Python code which could do this; there is a code path which
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
193 allows control to flow back to the user from a \cfunction{Py_DECREF()},
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
194 so almost any operation is potentially dangerous.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
195
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
196 A safe approach is to always use the generic operations (functions
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
197 whose name begins with \samp{PyObject_}, \samp{PyNumber_},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
198 \samp{PySequence_} or \samp{PyMapping_}). These operations always
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
199 increment the reference count of the object they return. This leaves
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
200 the caller with the responsibility to call
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
201 \cfunction{Py_DECREF()} when they are done with the result; this soon
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
202 becomes second nature.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
203
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
204
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
205 \subsubsection{Reference Count Details \label{refcountDetails}}
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
206
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
207 The reference count behavior of functions in the Python/C API is best
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
208 explained in terms of \emph{ownership of references}. Note that we
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
209 talk of owning references, never of owning objects; objects are always
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
210 shared! When a function owns a reference, it has to dispose of it
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
211 properly --- either by passing ownership on (usually to its caller) or
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
212 by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
213 a function passes ownership of a reference on to its caller, the
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
214 caller is said to receive a \emph{new} reference. When no ownership
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
215 is transferred, the caller is said to \emph{borrow} the reference.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
216 Nothing needs to be done for a borrowed reference.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
217
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
218 Conversely, when a calling function passes it a reference to an
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
219 object, there are two possibilities: the function \emph{steals} a
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
220 reference to the object, or it does not. Few functions steal
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
221 references; the two notable exceptions are
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
222 \cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
223 \cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
224 steal a reference to the item (but not to the tuple or list into which
8029
95142c8a09c8 Typo: (and often severly limited) -- severely
Fred Drake <fdrake@acm.org>
parents: 8021
diff changeset
225 the item is put!). These functions were designed to steal a reference
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
226 because of a common idiom for populating a tuple or list with newly
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
227 created objects; for example, the code to create the tuple \code{(1,
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
228 2, "three")} could look like this (forgetting about error handling for
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
229 the moment; a better way to code this is shown below):
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
230
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
231 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
232 PyObject *t;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
233
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
234 t = PyTuple_New(3);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
235 PyTuple_SetItem(t, 0, PyInt_FromLong(1L));
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
236 PyTuple_SetItem(t, 1, PyInt_FromLong(2L));
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
237 PyTuple_SetItem(t, 2, PyString_FromString("three"));
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
238 \end{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
239
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
240 Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
241 set tuple items; \cfunction{PySequence_SetItem()} and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
242 \cfunction{PyObject_SetItem()} refuse to do this since tuples are an
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
243 immutable data type. You should only use
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
244 \cfunction{PyTuple_SetItem()} for tuples that you are creating
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
245 yourself.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
246
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
247 Equivalent code for populating a list can be written using
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
248 \cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
249 can also use \cfunction{PySequence_SetItem()}; this illustrates the
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
250 difference between the two (the extra \cfunction{Py_DECREF()} calls):
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
251
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
252 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
253 PyObject *l, *x;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
254
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
255 l = PyList_New(3);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
256 x = PyInt_FromLong(1L);
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
257 PySequence_SetItem(l, 0, x); Py_DECREF(x);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
258 x = PyInt_FromLong(2L);
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
259 PySequence_SetItem(l, 1, x); Py_DECREF(x);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
260 x = PyString_FromString("three");
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
261 PySequence_SetItem(l, 2, x); Py_DECREF(x);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
262 \end{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
263
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
264 You might find it strange that the ``recommended'' approach takes more
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
265 code. However, in practice, you will rarely use these ways of
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
266 creating and populating a tuple or list. There's a generic function,
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
267 \cfunction{Py_BuildValue()}, that can create most common objects from
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
268 C values, directed by a \dfn{format string}. For example, the
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
269 above two blocks of code could be replaced by the following (which
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
270 also takes care of the error checking):
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
271
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
272 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
273 PyObject *t, *l;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
274
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
275 t = Py_BuildValue("(iis)", 1, 2, "three");
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
276 l = Py_BuildValue("[iis]", 1, 2, "three");
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
277 \end{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
278
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
279 It is much more common to use \cfunction{PyObject_SetItem()} and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
280 friends with items whose references you are only borrowing, like
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
281 arguments that were passed in to the function you are writing. In
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
282 that case, their behaviour regarding reference counts is much saner,
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
283 since you don't have to increment a reference count so you can give a
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
284 reference away (``have it be stolen''). For example, this function
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
285 sets all items of a list (actually, any mutable sequence) to a given
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
286 item:
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
287
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
288 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
289 int set_all(PyObject *target, PyObject *item)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
290 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
291 int i, n;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
292
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
293 n = PyObject_Length(target);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
294 if (n < 0)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
295 return -1;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
296 for (i = 0; i < n; i++) {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
297 if (PyObject_SetItem(target, i, item) < 0)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
298 return -1;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
299 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
300 return 0;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
301 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
302 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
303 \ttindex{set_all()}
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
304
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
305 The situation is slightly different for function return values.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
306 While passing a reference to most functions does not change your
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
307 ownership responsibilities for that reference, many functions that
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
308 return a referece to an object give you ownership of the reference.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
309 The reason is simple: in many cases, the returned object is created
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
310 on the fly, and the reference you get is the only reference to the
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
311 object. Therefore, the generic functions that return object
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
312 references, like \cfunction{PyObject_GetItem()} and
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
313 \cfunction{PySequence_GetItem()}, always return a new reference (the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
314 caller becomes the owner of the reference).
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
315
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
316 It is important to realize that whether you own a reference returned
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
317 by a function depends on which function you call only --- \emph{the
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
318 plumage} (the type of the type of the object passed as an
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
319 argument to the function) \emph{doesn't enter into it!} Thus, if you
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
320 extract an item from a list using \cfunction{PyList_GetItem()}, you
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
321 don't own the reference --- but if you obtain the same item from the
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
322 same list using \cfunction{PySequence_GetItem()} (which happens to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
323 take exactly the same arguments), you do own a reference to the
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
324 returned object.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
325
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
326 Here is an example of how you could write a function that computes the
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
327 sum of the items in a list of integers; once using
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
328 \cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
329 \cfunction{PySequence_GetItem()}\ttindex{PySequence_GetItem()}.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
330
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
331 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
332 long sum_list(PyObject *list)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
333 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
334 int i, n;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
335 long total = 0;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
336 PyObject *item;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
337
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
338 n = PyList_Size(list);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
339 if (n < 0)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
340 return -1; /* Not a list */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
341 for (i = 0; i < n; i++) {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
342 item = PyList_GetItem(list, i); /* Can't fail */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
343 if (!PyInt_Check(item)) continue; /* Skip non-integers */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
344 total += PyInt_AsLong(item);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
345 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
346 return total;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
347 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
348 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
349 \ttindex{sum_list()}
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
350
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
351 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
352 long sum_sequence(PyObject *sequence)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
353 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
354 int i, n;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
355 long total = 0;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
356 PyObject *item;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
357 n = PySequence_Length(sequence);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
358 if (n < 0)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
359 return -1; /* Has no length */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
360 for (i = 0; i < n; i++) {
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
361 item = PySequence_GetItem(sequence, i);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
362 if (item == NULL)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
363 return -1; /* Not a sequence, or other failure */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
364 if (PyInt_Check(item))
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
365 total += PyInt_AsLong(item);
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
366 Py_DECREF(item); /* Discard reference ownership */
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
367 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
368 return total;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
369 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
370 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
371 \ttindex{sum_sequence()}
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
372
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
373
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
374 \subsection{Types \label{types}}
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
375
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
376 There are few other data types that play a significant role in
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
377 the Python/C API; most are simple C types such as \ctype{int},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
378 \ctype{long}, \ctype{double} and \ctype{char*}. A few structure types
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
379 are used to describe static tables used to list the functions exported
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
380 by a module or the data attributes of a new object type, and another
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
381 is used to describe the value of a complex number. These will
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
382 be discussed together with the functions that use them.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
383
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
384
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
385 \section{Exceptions \label{exceptions}}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
386
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
387 The Python programmer only needs to deal with exceptions if specific
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
388 error handling is required; unhandled exceptions are automatically
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
389 propagated to the caller, then to the caller's caller, and so on, until
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
390 they reach the top-level interpreter, where they are reported to the
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
391 user accompanied by a stack traceback.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
392
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
393 For C programmers, however, error checking always has to be explicit.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
394 All functions in the Python/C API can raise exceptions, unless an
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
395 explicit claim is made otherwise in a function's documentation. In
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
396 general, when a function encounters an error, it sets an exception,
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
397 discards any object references that it owns, and returns an
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
398 error indicator --- usually \NULL{} or \code{-1}. A few functions
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
399 return a Boolean true/false result, with false indicating an error.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
400 Very few functions return no explicit error indicator or have an
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
401 ambiguous return value, and require explicit testing for errors with
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
402 \cfunction{PyErr_Occurred()}\ttindex{PyErr_Occurred()}.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
403
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
404 Exception state is maintained in per-thread storage (this is
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
405 equivalent to using global storage in an unthreaded application). A
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
406 thread can be in one of two states: an exception has occurred, or not.
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
407 The function \cfunction{PyErr_Occurred()} can be used to check for
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
408 this: it returns a borrowed reference to the exception type object
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
409 when an exception has occurred, and \NULL{} otherwise. There are a
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
410 number of functions to set the exception state:
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
411 \cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
412 common (though not the most general) function to set the exception
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
413 state, and \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} clears the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
414 exception state.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
415
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
416 The full exception state consists of three objects (all of which can
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
417 be \NULL{}): the exception type, the corresponding exception
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
418 value, and the traceback. These have the same meanings as the Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
419 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
420 \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
421 objects \code{sys.exc_type}, \code{sys.exc_value}, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
422 \code{sys.exc_traceback}; however, they are not the same: the Python
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
423 objects represent the last exception being handled by a Python
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
424 \keyword{try} \ldots\ \keyword{except} statement, while the C level
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
425 exception state only exists while an exception is being passed on
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
426 between C functions until it reaches the Python bytecode interpreter's
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
427 main loop, which takes care of transferring it to \code{sys.exc_type}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
428 and friends.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
429
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
430 Note that starting with Python 1.5, the preferred, thread-safe way to
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
431 access the exception state from Python code is to call the function
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
432 \withsubitem{(in module sys)}{\ttindex{exc_info()}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
433 \function{sys.exc_info()}, which returns the per-thread exception state
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
434 for Python code. Also, the semantics of both ways to access the
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
435 exception state have changed so that a function which catches an
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
436 exception will save and restore its thread's exception state so as to
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
437 preserve the exception state of its caller. This prevents common bugs
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
438 in exception handling code caused by an innocent-looking function
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
439 overwriting the exception being handled; it also reduces the often
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
440 unwanted lifetime extension for objects that are referenced by the
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
441 stack frames in the traceback.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
442
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
443 As a general principle, a function that calls another function to
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
444 perform some task should check whether the called function raised an
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
445 exception, and if so, pass the exception state on to its caller. It
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
446 should discard any object references that it owns, and return an
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
447 error indicator, but it should \emph{not} set another exception ---
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
448 that would overwrite the exception that was just raised, and lose
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
449 important information about the exact cause of the error.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
450
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
451 A simple example of detecting exceptions and passing them on is shown
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
452 in the \cfunction{sum_sequence()}\ttindex{sum_sequence()} example
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
453 above. It so happens that that example doesn't need to clean up any
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
454 owned references when it detects an error. The following example
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
455 function shows some error cleanup. First, to remind you why you like
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
456 Python, we show the equivalent Python code:
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
457
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
458 \begin{verbatim}
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
459 def incr_item(dict, key):
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
460 try:
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
461 item = dict[key]
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
462 except KeyError:
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
463 item = 0
15453
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
464 dict[key] = item + 1
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
465 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
466 \ttindex{incr_item()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
467
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
468 Here is the corresponding C code, in all its glory:
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
469
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
470 \begin{verbatim}
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
471 int incr_item(PyObject *dict, PyObject *key)
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
472 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
473 /* Objects all initialized to NULL for Py_XDECREF */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
474 PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
475 int rv = -1; /* Return value initialized to -1 (failure) */
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
476
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
477 item = PyObject_GetItem(dict, key);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
478 if (item == NULL) {
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
479 /* Handle KeyError only: */
15453
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
480 if (!PyErr_ExceptionMatches(PyExc_KeyError))
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
481 goto error;
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
482
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
483 /* Clear the error and use zero: */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
484 PyErr_Clear();
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
485 item = PyInt_FromLong(0L);
15453
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
486 if (item == NULL)
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
487 goto error;
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
488 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
489 const_one = PyInt_FromLong(1L);
15453
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
490 if (const_one == NULL)
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
491 goto error;
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
492
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
493 incremented_item = PyNumber_Add(item, const_one);
15453
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
494 if (incremented_item == NULL)
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
495 goto error;
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
496
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
497 if (PyObject_SetItem(dict, key, incremented_item) < 0)
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
498 goto error;
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
499 rv = 0; /* Success */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
500 /* Continue with cleanup code */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
501
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
502 error:
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
503 /* Cleanup code, shared by success and failure path */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
504
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
505 /* Use Py_XDECREF() to ignore NULL references */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
506 Py_XDECREF(item);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
507 Py_XDECREF(const_one);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
508 Py_XDECREF(incremented_item);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
509
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
510 return rv; /* -1 for error, 0 for success */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
511 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
512 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
513 \ttindex{incr_item()}
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
514
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
515 This example represents an endorsed use of the \keyword{goto} statement
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
516 in C! It illustrates the use of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
517 \cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
518 \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
519 handle specific exceptions, and the use of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
520 \cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
521 dispose of owned references that may be \NULL{} (note the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
522 \character{X} in the name; \cfunction{Py_DECREF()} would crash when
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
523 confronted with a \NULL{} reference). It is important that the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
524 variables used to hold owned references are initialized to \NULL{} for
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
525 this to work; likewise, the proposed return value is initialized to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
526 \code{-1} (failure) and only set to success after the final call made
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
527 is successful.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
528
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
529
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
530 \section{Embedding Python \label{embedding}}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
531
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
532 The one important task that only embedders (as opposed to extension
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
533 writers) of the Python interpreter have to worry about is the
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
534 initialization, and possibly the finalization, of the Python
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
535 interpreter. Most functionality of the interpreter can only be used
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
536 after the interpreter has been initialized.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
537
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
538 The basic initialization function is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
539 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
540 This initializes the table of loaded modules, and creates the
7310
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
541 fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
542 \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
543 \module{sys}\refbimodindex{sys}. It also initializes the module
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
544 search path (\code{sys.path}).%
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
545 \indexiii{module}{search}{path}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
546 \withsubitem{(in module sys)}{\ttindex{path}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
547
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
548 \cfunction{Py_Initialize()} does not set the ``script argument list''
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
549 (\code{sys.argv}). If this variable is needed by Python code that
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
550 will be executed later, it must be set explicitly with a call to
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
551 \code{PySys_SetArgv(\var{argc},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
552 \var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
553 \cfunction{Py_Initialize()}.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
554
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
555 On most systems (in particular, on \UNIX{} and Windows, although the
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
556 details are slightly different),
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
557 \cfunction{Py_Initialize()} calculates the module search path based
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
558 upon its best guess for the location of the standard Python
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
559 interpreter executable, assuming that the Python library is found in a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
560 fixed location relative to the Python interpreter executable. In
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
561 particular, it looks for a directory named
14557
a71385f8b4da Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents: 14553
diff changeset
562 \file{lib/python\shortversion} relative to the parent directory where
a71385f8b4da Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents: 14553
diff changeset
563 the executable named \file{python} is found on the shell command
a71385f8b4da Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents: 14553
diff changeset
564 search path (the environment variable \envvar{PATH}).
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
565
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
566 For instance, if the Python executable is found in
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
567 \file{/usr/local/bin/python}, it will assume that the libraries are in
14557
a71385f8b4da Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents: 14553
diff changeset
568 \file{/usr/local/lib/python\shortversion}. (In fact, this particular path
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
569 is also the ``fallback'' location, used when no executable file named
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
570 \file{python} is found along \envvar{PATH}.) The user can override
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
571 this behavior by setting the environment variable \envvar{PYTHONHOME},
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
572 or insert additional directories in front of the standard path by
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
573 setting \envvar{PYTHONPATH}.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
574
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
575 The embedding application can steer the search by calling
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
576 \code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
577 \cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
578 overrides this and \envvar{PYTHONPATH} is still inserted in front of
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
579 the standard path. An application that requires total control has to
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
580 provide its own implementation of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
581 \cfunction{Py_GetPath()}\ttindex{Py_GetPath()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
582 \cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
583 \cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
584 \cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
585 defined in \file{Modules/getpath.c}).
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
586
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
587 Sometimes, it is desirable to ``uninitialize'' Python. For instance,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
588 the application may want to start over (make another call to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
589 \cfunction{Py_Initialize()}) or the application is simply done with its
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
590 use of Python and wants to free all memory allocated by Python. This
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
591 can be accomplished by calling \cfunction{Py_Finalize()}. The function
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
592 \cfunction{Py_IsInitialized()}\ttindex{Py_IsInitialized()} returns
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
593 true if Python is currently in the initialized state. More
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
594 information about these functions is given in a later chapter.
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
595
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
596
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
597 \chapter{The Very High Level Layer \label{veryhigh}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
598
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
599 The functions in this chapter will let you execute Python source code
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
600 given in a file or a buffer, but they will not let you interact in a
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
601 more detailed way with the interpreter.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
602
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
603 Several of these functions accept a start symbol from the grammar as a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
604 parameter. The available start symbols are \constant{Py_eval_input},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
605 \constant{Py_file_input}, and \constant{Py_single_input}. These are
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
606 described following the functions which accept them as parameters.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
607
13959
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
608 Note also that several of these functions take \ctype{FILE*}
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
609 parameters. On particular issue which needs to be handled carefully
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
610 is that the \ctype{FILE} structure for different C libraries can be
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
611 different and incompatible. Under Windows (at least), it is possible
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
612 for dynamically linked extensions to actually use different libraries,
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
613 so care should be taken that \ctype{FILE*} parameters are only passed
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
614 to these functions if it is certain that they were created by the same
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
615 library that the Python runtime is using.
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
616
17877
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
617 \begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
618 The main program for the standard interpreter. This is made
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
619 available for programs which embed Python. The \var{argc} and
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
620 \var{argv} parameters should be prepared exactly as those which are
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
621 passed to a C program's \cfunction{main()} function. It is
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
622 important to note that the argument list may be modified (but the
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
623 contents of the strings pointed to by the argument list are not).
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
624 The return value will be the integer passed to the
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
625 \function{sys.exit()} function, \code{1} if the interpreter exits
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
626 due to an exception, or \code{2} if the parameter list does not
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
627 represent a valid Python command line.
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
628 \end{cfuncdesc}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
629
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
630 \begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
631 If \var{fp} refers to a file associated with an interactive device
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
632 (console or terminal input or \UNIX{} pseudo-terminal), return the
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
633 value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
634 result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
635 \NULL{}, this function uses \code{"???"} as the filename.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
636 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
637
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
638 \begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
639 Executes the Python source code from \var{command} in the
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
640 \module{__main__} module. If \module{__main__} does not already
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
641 exist, it is created. Returns \code{0} on success or \code{-1} if
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
642 an exception was raised. If there was an error, there is no way to
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
643 get the exception information.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
644 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
645
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
646 \begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
647 Similar to \cfunction{PyRun_SimpleString()}, but the Python source
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
648 code is read from \var{fp} instead of an in-memory string.
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
649 \var{filename} should be the name of the file.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
650 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
651
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
652 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
653 Read and execute a single statement from a file associated with an
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
654 interactive device. If \var{filename} is \NULL, \code{"???"} is
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
655 used instead. The user will be prompted using \code{sys.ps1} and
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
656 \code{sys.ps2}. Returns \code{0} when the input was executed
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
657 successfully, \code{-1} if there was an exception, or an error code
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
658 from the \file{errcode.h} include file distributed as part of Python
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
659 in case of a parse error. (Note that \file{errcode.h} is not
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
660 included by \file{Python.h}, so must be included specifically if
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
661 needed.)
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
662 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
663
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
664 \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
665 Read and execute statements from a file associated with an
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
666 interactive device until \EOF{} is reached. If \var{filename} is
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
667 \NULL, \code{"???"} is used instead. The user will be prompted
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
668 using \code{sys.ps1} and \code{sys.ps2}. Returns \code{0} at \EOF.
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
669 \end{cfuncdesc}
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
670
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
671 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
672 int start}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
673 Parse Python source code from \var{str} using the start token
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
674 \var{start}. The result can be used to create a code object which
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
675 can be evaluated efficiently. This is useful if a code fragment
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
676 must be evaluated many times.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
677 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
678
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
679 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
680 char *filename, int start}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
681 Similar to \cfunction{PyParser_SimpleParseString()}, but the Python
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
682 source code is read from \var{fp} instead of an in-memory string.
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
683 \var{filename} should be the name of the file.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
684 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
685
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
686 \begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
687 PyObject *globals,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
688 PyObject *locals}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
689 Execute Python source code from \var{str} in the context specified
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
690 by the dictionaries \var{globals} and \var{locals}. The parameter
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
691 \var{start} specifies the start token that should be used to parse
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
692 the source code.
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
693
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
694 Returns the result of executing the code as a Python object, or
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
695 \NULL{} if an exception was raised.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
696 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
697
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
698 \begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
699 int start, PyObject *globals,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
700 PyObject *locals}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
701 Similar to \cfunction{PyRun_String()}, but the Python source code is
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
702 read from \var{fp} instead of an in-memory string.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
703 \var{filename} should be the name of the file.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
704 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
705
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
706 \begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
707 int start}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
708 Parse and compile the Python source code in \var{str}, returning the
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
709 resulting code object. The start token is given by \var{start};
11222
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
710 this can be used to constrain the code which can be compiled and should
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
711 be \constant{Py_eval_input}, \constant{Py_file_input}, or
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
712 \constant{Py_single_input}. The filename specified by
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
713 \var{filename} is used to construct the code object and may appear
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
714 in tracebacks or \exception{SyntaxError} exception messages. This
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
715 returns \NULL{} if the code cannot be parsed or compiled.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
716 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
717
11222
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
718 \begin{cvardesc}{int}{Py_eval_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
719 The start symbol from the Python grammar for isolated expressions;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
720 for use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
11222
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
721 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
722
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
723 \begin{cvardesc}{int}{Py_file_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
724 The start symbol from the Python grammar for sequences of statements
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
725 as read from a file or other source; for use with
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
726 \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. This is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
727 the symbol to use when compiling arbitrarily long Python source code.
11222
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
728 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
729
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
730 \begin{cvardesc}{int}{Py_single_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
731 The start symbol from the Python grammar for a single statement; for
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
732 use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
733 This is the symbol used for the interactive interpreter loop.
11222
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
734 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
735
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
736
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
737 \chapter{Reference Counting \label{countingRefs}}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
738
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
739 The macros in this section are used for managing reference counts
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
740 of Python objects.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
741
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
742 \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
743 Increment the reference count for object \var{o}. The object must
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
744 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
745 \cfunction{Py_XINCREF()}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
746 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
747
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
748 \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
749 Increment the reference count for object \var{o}. The object may be
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
750 \NULL{}, in which case the macro has no effect.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
751 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
752
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
753 \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
754 Decrement the reference count for object \var{o}. The object must
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
755 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
756 \cfunction{Py_XDECREF()}. If the reference count reaches zero, the
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
757 object's type's deallocation function (which must not be \NULL{}) is
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
758 invoked.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
759
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
760 \strong{Warning:} The deallocation function can cause arbitrary Python
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
761 code to be invoked (e.g. when a class instance with a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
762 \method{__del__()} method is deallocated). While exceptions in such
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
763 code are not propagated, the executed code has free access to all
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
764 Python global variables. This means that any object that is reachable
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
765 from a global variable should be in a consistent state before
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
766 \cfunction{Py_DECREF()} is invoked. For example, code to delete an
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
767 object from a list should copy a reference to the deleted object in a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
768 temporary variable, update the list data structure, and then call
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
769 \cfunction{Py_DECREF()} for the temporary variable.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
770 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
771
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
772 \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
773 Decrement the reference count for object \var{o}. The object may be
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
774 \NULL{}, in which case the macro has no effect; otherwise the effect
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
775 is the same as for \cfunction{Py_DECREF()}, and the same warning
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
776 applies.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
777 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
778
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
779 The following functions or macros are only for use within the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
780 interpreter core: \cfunction{_Py_Dealloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
781 \cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
782 well as the global variable \cdata{_Py_RefTotal}.
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
783
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
784
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
785 \chapter{Exception Handling \label{exceptionHandling}}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
786
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
787 The functions described in this chapter will let you handle and raise Python
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
788 exceptions. It is important to understand some of the basics of
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
789 Python exception handling. It works somewhat like the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
790 \UNIX{} \cdata{errno} variable: there is a global indicator (per
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
791 thread) of the last error that occurred. Most functions don't clear
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
792 this on success, but will set it to indicate the cause of the error on
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
793 failure. Most functions also return an error indicator, usually
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
794 \NULL{} if they are supposed to return a pointer, or \code{-1} if they
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
795 return an integer (exception: the \cfunction{PyArg_Parse*()} functions
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
796 return \code{1} for success and \code{0} for failure). When a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
797 function must fail because some function it called failed, it
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
798 generally doesn't set the error indicator; the function it called
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
799 already set it.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
800
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
801 The error indicator consists of three Python objects corresponding to
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
802 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
803 \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
804 the Python variables \code{sys.exc_type}, \code{sys.exc_value} and
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
805 \code{sys.exc_traceback}. API functions exist to interact with the
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
806 error indicator in various ways. There is a separate error indicator
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
807 for each thread.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
808
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
809 % XXX Order of these should be more thoughtful.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
810 % Either alphabetical or some kind of structure.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
811
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
812 \begin{cfuncdesc}{void}{PyErr_Print}{}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
813 Print a standard traceback to \code{sys.stderr} and clear the error
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
814 indicator. Call this function only when the error indicator is set.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
815 (Otherwise it will cause a fatal error!)
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
816 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
817
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
818 \begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
819 Test whether the error indicator is set. If set, return the exception
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
820 \emph{type} (the first argument to the last call to one of the
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
821 \cfunction{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}). If
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
822 not set, return \NULL{}. You do not own a reference to the return
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
823 value, so you do not need to \cfunction{Py_DECREF()} it.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
824 \strong{Note:} Do not compare the return value to a specific
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
825 exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
826 below. (The comparison could easily fail since the exception may be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
827 an instance instead of a class, in the case of a class exception, or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
828 it may the a subclass of the expected exception.)
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
829 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
830
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
831 \begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
832 Equivalent to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
833 \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
834 This should only be called when an exception is actually set; a memory
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
835 access violation will occur if no exception has been raised.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
836 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
837
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
838 \begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
839 Return true if the \var{given} exception matches the exception in
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
840 \var{exc}. If \var{exc} is a class object, this also returns true
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
841 when \var{given} is an instance of a subclass. If \var{exc} is a tuple, all
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
842 exceptions in the tuple (and recursively in subtuples) are searched
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
843 for a match. If \var{given} is \NULL, a memory access violation will
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
844 occur.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
845 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
846
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
847 \begin{cfuncdesc}{void}{PyErr_NormalizeException}{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
848 Under certain circumstances, the values returned by
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
849 \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
850 \code{*\var{exc}} is a class object but \code{*\var{val}} is not an
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
851 instance of the same class. This function can be used to instantiate
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
852 the class in that case. If the values are already normalized, nothing
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
853 happens. The delayed normalization is implemented to improve
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
854 performance.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
855 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
856
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
857 \begin{cfuncdesc}{void}{PyErr_Clear}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
858 Clear the error indicator. If the error indicator is not set, there
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
859 is no effect.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
860 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
861
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
862 \begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
863 PyObject **ptraceback}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
864 Retrieve the error indicator into three variables whose addresses are
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
865 passed. If the error indicator is not set, set all three variables to
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
866 \NULL{}. If it is set, it will be cleared and you own a reference to
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
867 each object retrieved. The value and traceback object may be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
868 \NULL{} even when the type object is not. \strong{Note:} This
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
869 function is normally only used by code that needs to handle exceptions
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
870 or by code that needs to save and restore the error indicator
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
871 temporarily.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
872 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
873
14279
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
874 \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value,
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
875 PyObject *traceback}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
876 Set the error indicator from the three objects. If the error
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
877 indicator is already set, it is cleared first. If the objects are
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
878 \NULL{}, the error indicator is cleared. Do not pass a \NULL{} type
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
879 and non-\NULL{} value or traceback. The exception type should be a
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
880 string or class; if it is a class, the value should be an instance of
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
881 that class. Do not pass an invalid exception type or value.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
882 (Violating these rules will cause subtle problems later.) This call
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
883 takes away a reference to each object: you must own a reference
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
884 to each object before the call and after the call you no longer own
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
885 these references. (If you don't understand this, don't use this
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
886 function. I warned you.) \strong{Note:} This function is normally
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
887 only used by code that needs to save and restore the error indicator
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
888 temporarily.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
889 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
890
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
891 \begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
892 This is the most common way to set the error indicator. The first
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
893 argument specifies the exception type; it is normally one of the
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
894 standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
895 increment its reference count. The second argument is an error
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
896 message; it is converted to a string object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
897 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
898
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
899 \begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
900 This function is similar to \cfunction{PyErr_SetString()} but lets you
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
901 specify an arbitrary Python object for the ``value'' of the exception.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
902 You need not increment its reference count.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
903 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
904
12355
04802b7e8a1f Yet another markup nit: functions that are part of the Python/C API
Fred Drake <fdrake@acm.org>
parents: 12354
diff changeset
905 \begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception,
14347
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
906 const char *format, \moreargs}
15236
f1ade8ab1869 For PyErr_Format(), note that the exception parameter can be a string or
Fred Drake <fdrake@acm.org>
parents: 15087
diff changeset
907 This function sets the error indicator. \var{exception} should be a
f1ade8ab1869 For PyErr_Format(), note that the exception parameter can be a string or
Fred Drake <fdrake@acm.org>
parents: 15087
diff changeset
908 Python exception (string or class, not an instance).
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
909 \var{format} should be a string, containing format codes, similar to
14347
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
910 \cfunction{printf}. The \code{width.precision} before a format code
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
911 is parsed, but the width part is ignored.
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
912
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
913 \begin{tableii}{c|l}{character}{Character}{Meaning}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
914 \lineii{c}{Character, as an \ctype{int} parameter}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
915 \lineii{d}{Number in decimal, as an \ctype{int} parameter}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
916 \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
917 \lineii{x}{A string, as a \ctype{char *} parameter}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
918 \end{tableii}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
919
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
920 An unrecognized format character causes all the rest of
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
921 the format string to be copied as-is to the result string,
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
922 and any extra arguments discarded.
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
923
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
924 A new reference is returned, which is owned by the caller.
12353
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
925 \end{cfuncdesc}
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
926
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
927 \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
928 This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
929 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
930
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
931 \begin{cfuncdesc}{int}{PyErr_BadArgument}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
932 This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
933 \var{message})}, where \var{message} indicates that a built-in operation
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
934 was invoked with an illegal argument. It is mostly for internal use.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
935 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
936
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
937 \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
938 This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
939 returns \NULL{} so an object allocation function can write
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
940 \samp{return PyErr_NoMemory();} when it runs out of memory.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
941 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
942
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
943 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
944 This is a convenience function to raise an exception when a C library
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
945 function has returned an error and set the C variable \cdata{errno}.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
946 It constructs a tuple object whose first item is the integer
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
947 \cdata{errno} value and whose second item is the corresponding error
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
948 message (gotten from \cfunction{strerror()}\ttindex{strerror()}), and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
949 then calls
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
950 \samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
951 the \cdata{errno} value is \constant{EINTR}, indicating an interrupted
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
952 system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
953 the error indicator, leaves it set to that. The function always
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
954 returns \NULL{}, so a wrapper function around a system call can write
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
955 \samp{return PyErr_SetFromErrno();} when the system call returns an
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
956 error.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
957 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
958
18192
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
959 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type,
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
960 char *filename}
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
961 Similar to \cfunction{PyErr_SetFromErrno()}, with the additional
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
962 behavior that if \var{filename} is not \NULL, it is passed to the
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
963 constructor of \var{type} as a third parameter. In the case of
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
964 exceptions such as \exception{IOError} and \exception{OSError}, this
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
965 is used to define the \member{filename} attribute of the exception
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
966 instance.
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
967 \end{cfuncdesc}
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
968
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
969 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
970 This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError,
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
971 \var{message})}, where \var{message} indicates that an internal
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
972 operation (e.g. a Python/C API function) was invoked with an illegal
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
973 argument. It is mostly for internal use.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
974 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
975
15613
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
976 \begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
977 Issue a warning message. The \var{category} argument is a warning
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
978 category (see below) or \NULL; the \var{message} argument is a message
15613
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
979 string.
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
980
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
981 This function normally prints a warning message to \var{sys.stderr};
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
982 however, it is also possible that the user has specified that warnings
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
983 are to be turned into errors, and in that case this will raise an
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
984 exception. It is also possible that the function raises an exception
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
985 because of a problem with the warning machinery (the implementation
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
986 imports the \module{warnings} module to do the heavy lifting). The
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
987 return value is \code{0} if no exception is raised, or \code{-1} if
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
988 an exception is raised. (It is not possible to determine whether a
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
989 warning message is actually printed, nor what the reason is for the
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
990 exception; this is intentional.) If an exception is raised, the
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
991 caller should do its normal exception handling
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
992 (e.g. \cfunction{Py_DECREF()} owned references and return an error
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
993 value).
15613
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
994
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
995 Warning categories must be subclasses of \cdata{Warning}; the default
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
996 warning category is \cdata{RuntimeWarning}. The standard Python
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
997 warning categories are available as global variables whose names are
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
998 \samp{PyExc_} followed by the Python exception name. These have the
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
999 type \ctype{PyObject*}; they are all class objects. Their names are
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1000 \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1001 \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1002 \cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass of
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1003 \cdata{PyExc_Exception}; the other warning categories are subclasses
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1004 of \cdata{PyExc_Warning}.
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1005
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1006 For information about warning control, see the documentation for the
15733
00c6855d742a Markup nit: Command line options should be marked with \programopt.
Fred Drake <fdrake@acm.org>
parents: 15613
diff changeset
1007 \module{warnings} module and the \programopt{-W} option in the command
00c6855d742a Markup nit: Command line options should be marked with \programopt.
Fred Drake <fdrake@acm.org>
parents: 15613
diff changeset
1008 line documentation. There is no C API for warning control.
15613
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1009 \end{cfuncdesc}
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1010
16872
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1011 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message,
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1012 char *filename, int lineno, char *module, PyObject *registry}
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1013 Issue a warning message with explicit control over all warning
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1014 attributes. This is a straightforward wrapper around the Python
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1015 function \function{warnings.warn_explicit()}, see there for more
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1016 information. The \var{module} and \var{registry} arguments may be
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1017 set to \code{NULL} to get the default effect described there.
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1018 \end{cfuncdesc}
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1019
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1020 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1021 This function interacts with Python's signal handling. It checks
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1022 whether a signal has been sent to the processes and if so, invokes the
7310
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
1023 corresponding signal handler. If the
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
1024 \module{signal}\refbimodindex{signal} module is supported, this can
6095a472f574 Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents: 7309
diff changeset
1025 invoke a signal handler written in Python. In all cases, the default
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1026 effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1027 \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1028 \exception{KeyboardInterrupt} exception. If an exception is raised the
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1029 error indicator is set and the function returns \code{1}; otherwise
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1030 the function returns \code{0}. The error indicator may or may not be
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1031 cleared if it was previously set.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1032 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1033
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1034 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1035 This function is obsolete. It simulates the effect of a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1036 \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1037 \cfunction{PyErr_CheckSignals()} is called,
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1038 \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1039 \exception{KeyboardInterrupt} will be raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1040 It may be called without holding the interpreter lock.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1041 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1042
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1043 \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1044 PyObject *base,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1045 PyObject *dict}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1046 This utility function creates and returns a new exception object. The
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1047 \var{name} argument must be the name of the new exception, a C string
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1048 of the form \code{module.class}. The \var{base} and
13150
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1049 \var{dict} arguments are normally \NULL{}. This creates a
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1050 class object derived from the root for all exceptions, the built-in
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1051 name \exception{Exception} (accessible in C as
13150
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1052 \cdata{PyExc_Exception}). The \member{__module__} attribute of the
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1053 new class is set to the first part (up to the last dot) of the
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1054 \var{name} argument, and the class name is set to the last part (after
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1055 the last dot). The \var{base} argument can be used to specify an
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1056 alternate base class. The \var{dict} argument can be used to specify
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1057 a dictionary of class variables and methods.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1058 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1059
14330
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1060 \begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj}
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1061 This utility function prints a warning message to \var{sys.stderr}
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1062 when an exception has been set but it is impossible for the
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1063 interpreter to actually raise the exception. It is used, for example,
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1064 when an exception occurs in an \member{__del__} method.
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1065
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1066 The function is called with a single argument \var{obj} that
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1067 identifies where the context in which the unraisable exception
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1068 occurred. The repr of \var{obj} will be printed in the warning
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1069 message.
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1070 \end{cfuncdesc}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1071
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1072 \section{Standard Exceptions \label{standardExceptions}}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1073
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1074 All standard Python exceptions are available as global variables whose
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1075 names are \samp{PyExc_} followed by the Python exception name. These
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1076 have the type \ctype{PyObject*}; they are all class objects. For
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1077 completeness, here are all the variables:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1078
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1079 \begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1080 \lineiii{PyExc_Exception}{\exception{Exception}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1081 \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1082 \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1083 \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1084 \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1085 \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1086 \lineiii{PyExc_EOFError}{\exception{EOFError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1087 \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1088 \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1089 \lineiii{PyExc_IOError}{\exception{IOError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1090 \lineiii{PyExc_ImportError}{\exception{ImportError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1091 \lineiii{PyExc_IndexError}{\exception{IndexError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1092 \lineiii{PyExc_KeyError}{\exception{KeyError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1093 \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1094 \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1095 \lineiii{PyExc_NameError}{\exception{NameError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1096 \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1097 \lineiii{PyExc_OSError}{\exception{OSError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1098 \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1099 \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1100 \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1101 \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1102 \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1103 \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1104 \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1105 \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(2)}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1106 \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1107 \end{tableiii}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1108
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1109 \noindent
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1110 Notes:
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1111 \begin{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1112 \item[(1)]
13150
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1113 This is a base class for other standard exceptions.
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1114
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1115 \item[(2)]
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1116 Only defined on Windows; protect code that uses this by testing that
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1117 the preprocessor macro \code{MS_WINDOWS} is defined.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1118 \end{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1119
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1120
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1121 \section{Deprecation of String Exceptions}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1122
13150
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1123 All exceptions built into Python or provided in the standard library
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1124 are derived from \exception{Exception}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1125 \withsubitem{(built-in exception)}{\ttindex{Exception}}
13150
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1126
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1127 String exceptions are still supported in the interpreter to allow
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1128 existing code to run unmodified, but this will also change in a future
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1129 release.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1130
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1131
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1132 \chapter{Utilities \label{utilities}}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1133
18785
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1134 The functions in this chapter perform various utility tasks, ranging
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1135 from helping C code be more portable across platforms, using Python
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1136 modules from C, and parsing function arguments and constructing Python
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1137 values from C values.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1138
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1139
18575
670464c94b92 Fix the markup of the caret charater in a couple of places; LaTeX's
Fred Drake <fdrake@acm.org>
parents: 18481
diff changeset
1140 \section{Operating System Utilities \label{os}}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1141
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1142 \begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1143 Return true (nonzero) if the standard I/O file \var{fp} with name
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1144 \var{filename} is deemed interactive. This is the case for files for
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1145 which \samp{isatty(fileno(\var{fp}))} is true. If the global flag
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
1146 \cdata{Py_InteractiveFlag} is true, this function also returns true if
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1147 the \var{filename} pointer is \NULL{} or if the name is equal to one of
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
1148 the strings \code{'<stdin>'} or \code{'???'}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1149 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1150
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1151 \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1152 Return the time of last modification of the file \var{filename}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1153 The result is encoded in the same way as the timestamp returned by
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1154 the standard C library function \cfunction{time()}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1155 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1156
13053
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1157 \begin{cfuncdesc}{void}{PyOS_AfterFork}{}
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1158 Function to update some internal state after a process fork; this
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1159 should be called in the new process if the Python interpreter will
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1160 continue to be used. If a new executable is loaded into the new
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1161 process, this function does not need to be called.
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1162 \end{cfuncdesc}
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1163
14279
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1164 \begin{cfuncdesc}{int}{PyOS_CheckStack}{}
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1165 Return true when the interpreter runs out of stack space. This is a
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1166 reliable check, but is only available when \code{USE_STACKCHECK} is
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1167 defined (currently on Windows using the Microsoft Visual C++ compiler
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1168 and on the Macintosh). \code{USE_CHECKSTACK} will be defined
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1169 automatically; you should never change the definition in your own
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1170 code.
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1171 \end{cfuncdesc}
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1172
14635
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1173 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1174 Return the current signal handler for signal \var{i}.
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1175 This is a thin wrapper around either \cfunction{sigaction} or
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1176 \cfunction{signal}. Do not call those functions directly!
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1177 \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}.
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1178 \end{cfuncdesc}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1179
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1180 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1181 Set the signal handler for signal \var{i} to be \var{h};
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1182 return the old signal handler.
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1183 This is a thin wrapper around either \cfunction{sigaction} or
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1184 \cfunction{signal}. Do not call those functions directly!
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1185 \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}.
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1186 \end{cfuncdesc}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1187
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1188
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1189 \section{Process Control \label{processControl}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1190
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1191 \begin{cfuncdesc}{void}{Py_FatalError}{char *message}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1192 Print a fatal error message and kill the process. No cleanup is
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1193 performed. This function should only be invoked when a condition is
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1194 detected that would make it dangerous to continue using the Python
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1195 interpreter; e.g., when the object administration appears to be
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1196 corrupted. On \UNIX{}, the standard C library function
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1197 \cfunction{abort()}\ttindex{abort()} is called which will attempt to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1198 produce a \file{core} file.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1199 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1200
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1201 \begin{cfuncdesc}{void}{Py_Exit}{int status}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1202 Exit the current process. This calls
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1203 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1204 then calls the standard C library function
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1205 \code{exit(\var{status})}\ttindex{exit()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1206 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1207
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1208 \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1209 Register a cleanup function to be called by
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1210 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1211 The cleanup function will be called with no arguments and should
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1212 return no value. At most 32 \index{cleanup functions}cleanup
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1213 functions can be registered.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1214 When the registration is successful, \cfunction{Py_AtExit()} returns
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1215 \code{0}; on failure, it returns \code{-1}. The cleanup function
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1216 registered last is called first. Each cleanup function will be called
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1217 at most once. Since Python's internal finallization will have
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1218 completed before the cleanup function, no Python APIs should be called
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1219 by \var{func}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1220 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1221
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1222
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1223 \section{Importing Modules \label{importing}}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1224
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1225 \begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1226 This is a simplified interface to
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1227 \cfunction{PyImport_ImportModuleEx()} below, leaving the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1228 \var{globals} and \var{locals} arguments set to \NULL{}. When the
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
1229 \var{name} argument contains a dot (when it specifies a
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1230 submodule of a package), the \var{fromlist} argument is set to the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1231 list \code{['*']} so that the return value is the named module rather
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1232 than the top-level package containing it as would otherwise be the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1233 case. (Unfortunately, this has an additional side effect when
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1234 \var{name} in fact specifies a subpackage instead of a submodule: the
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1235 submodules specified in the package's \code{__all__} variable are
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1236 \index{package variable!\code{__all__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1237 \withsubitem{(package variable)}{\ttindex{__all__}}loaded.) Return a
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1238 new reference to the imported module, or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1239 \NULL{} with an exception set on failure (the module may still be
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1240 created in this case --- examine \code{sys.modules} to find out).
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1241 \withsubitem{(in module sys)}{\ttindex{modules}}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1242 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1243
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1244 \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
1245 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
1246 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
1247 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
1248 directly.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1249
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1250 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
1251 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
1252 (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
1253 \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
1254 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
1255 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
1256 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1257
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1258 \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
1259 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
1260 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
1261 \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
1262 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
1263 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
1264 \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
1265 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1266
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1267 \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
1268 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
1269 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
1270 \function{reload()} function calls this function directly. Return a
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1271 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
1272 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
1273 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1274
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1275 \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
1276 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
1277 \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
1278 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
1279 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
1280 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
1281 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
1282 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
1283 import a module.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1284 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
1285 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1286
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1287 \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
1288 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
1289 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
1290 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
1291 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
1292 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
1293 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
1294 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
1295 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1296
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1297 \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
1298 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
1299 \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
1300 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
1301 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
1302 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1303
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1304 \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
1305 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
1306 (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
1307 variable.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1308 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1309
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1310 \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
1311 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
1312 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1313
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1314 \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
1315 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
1316 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1317
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1318 \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
1319 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
1320 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1321
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1322 \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
1323 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
1324 \end{cfuncdesc}
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
1325
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1326 \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
1327 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
1328 \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
1329
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
1330 \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
1331 Load a frozen module named \var{name}. Return \code{1} for success,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
1332 \code{0} if the module is not found, and \code{-1} with an exception
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
1333 set if the initialization failed. To access the imported module on a
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
1334 successful load, use \cfunction{PyImport_ImportModule()}.
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1335 (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
1336 already imported.)
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1337 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1338
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1339 \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
1340 This is the structure type definition for frozen module descriptors,
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1341 as generated by the \program{freeze}\index{freeze utility} utility
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1342 (see \file{Tools/freeze/} in the Python source distribution). Its
14337
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1343 definition, found in \file{Include/import.h}, is:
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1344
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1345 \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
1346 struct _frozen {
6480
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1347 char *name;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1348 unsigned char *code;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1349 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
1350 };
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1351 \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
1352 \end{ctypedesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1353
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1354 \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
1355 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
1356 _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
1357 \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
1358 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
1359 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
1360 \end{cvardesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1361
14337
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1362 \begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1363 void (*initfunc)(void)}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1364 Add a single module to the existing table of built-in modules. This
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1365 is a convenience wrapper around \cfunction{PyImport_ExtendInittab()},
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1366 returning \code{-1} if the table could not be extended. The new
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1367 module can be imported by the name \var{name}, and uses the function
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1368 \var{initfunc} as the initialization function called on the first
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1369 attempted import. This should be called before
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1370 \cfunction{Py_Initialize()}.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1371 \end{cfuncdesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1372
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1373 \begin{ctypedesc}[_inittab]{struct _inittab}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1374 Structure describing a single entry in the list of built-in modules.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1375 Each of these structures gives the name and initialization function
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1376 for a module built into the interpreter. Programs which embed Python
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1377 may use an array of these structures in conjunction with
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1378 \cfunction{PyImport_ExtendInittab()} to provide additional built-in
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1379 modules. The structure is defined in \file{Include/import.h} as:
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1380
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1381 \begin{verbatim}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1382 struct _inittab {
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1383 char *name;
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1384 void (*initfunc)(void);
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1385 };
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1386 \end{verbatim}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1387 \end{ctypedesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1388
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1389 \begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1390 Add a collection of modules to the table of built-in modules. The
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1391 \var{newtab} array must end with a sentinel entry which contains
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1392 \NULL{} for the \member{name} field; failure to provide the sentinel
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1393 value can result in a memory fault. Returns \code{0} on success or
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1394 \code{-1} if insufficient memory could be allocated to extend the
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1395 internal table. In the event of failure, no modules are added to the
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1396 internal table. This should be called before
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1397 \cfunction{Py_Initialize()}.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1398 \end{cfuncdesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1399
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1400
18785
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1401 \section{Parsing arguements and building values
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1402 \label{arg-parsing}}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1403
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1404 These functions are useful when creating your own extensions functions
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1405 and methods. Additional information and examples are available in
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1406 \citetitle[../ext/ext.html]{Extending and Embedding the Python
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1407 Interpreter}.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1408
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1409 \begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1410 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1411 Parse the parameters of a function that takes only positional
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1412 parameters into local variables. Returns true on success; on
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1413 failure, it returns false and raises the appropriate exception. See
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1414 \citetitle[../ext/parseTuple.html]{Extending and Embedding the
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1415 Python Interpreter} for more information.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1416 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1417
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1418 \begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1419 PyObject *kw, char *format, char *keywords[],
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1420 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1421 Parse the parameters of a function that takes both positional and
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1422 keyword parameters into local variables. Returns true on success;
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1423 on failure, it returns false and raises the appropriate exception.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1424 See \citetitle[../ext/parseTupleAndKeywords.html]{Extending and
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1425 Embedding the Python Interpreter} for more information.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1426 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1427
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1428 \begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1429 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1430 Function used to deconstruct the argument lists of ``old-style''
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1431 functions --- these are functions which use the
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1432 \constant{METH_OLDARGS} parameter parsing method. This is not
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1433 recommended for use in parameter parsing in new code, and most code
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1434 in the standard interpreter has been modified to no longer use this
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1435 for that purpose. It does remain a convenient way to decompose
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1436 other tuples, however, and may continue to be used for that
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1437 purpose.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1438 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1439
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1440 \begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1441 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1442 Create a new value based on a format string similar to those
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1443 accepted by the \cfunction{PyArg_Parse*()} family of functions and a
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1444 sequence of values. Returns the value or \NULL{} in the case of an
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1445 error; an exception will be raised if \NULL{} is returned. For more
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1446 information on the format string and additional parameters, see
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1447 \citetitle[../ext/buildValue.html]{Extending and Embedding the
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1448 Python Interpreter}.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1449 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1450
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1451
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1452
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1453 \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
1454
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1455 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
1456 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
1457 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
1458 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
1459
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1460 \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
1461
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1462 \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
1463 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
1464 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
1465 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
1466 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
1467 \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
1468 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1469
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1470 \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
1471 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
1472 \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
1473 \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
1474 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
1475 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1476
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1477 \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
1478 char *attr_name}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1479 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
1480 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
1481 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1482 \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
1483 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1484
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1485
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1486 \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
1487 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
1488 \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
1489 \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
1490 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
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
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1494 \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
1495 PyObject *attr_name}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1496 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
1497 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
1498 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1499 \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
1500 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1501
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1502
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1503 \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
1504 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
1505 \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
1506 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
1507 \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
1508 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1509
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1510
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1511 \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
1512 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
1513 object \var{o},
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1514 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
1515 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
1516 \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
1517 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1518
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1519
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1520 \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
1521 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
1522 \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
1523 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
1524 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1525
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1526
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1527 \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
1528 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
1529 \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
1530 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
1531 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1532
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1533
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1534 \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
1535 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
1536 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
1537 \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
1538 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
1539 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
1540 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1541
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1542
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1543 \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
1544 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
1545 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
1546 \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
1547 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
1548 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
1549 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
1550 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1551
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1552
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1553 \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
1554 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
1555 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
1556 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
1557 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
1558 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
1559 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1562 \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
1563 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
1564 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
1565 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
1566 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
1567 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
1568 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1569
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1570
15952
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1571 \begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o}
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1572 Compute a Unicode string representation of object \var{o}. Returns the
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1573 Unicode string representation on success, \NULL{} on failure. This is
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1574 the equivalent of the Python expression \samp{unistr(\var{o})}.
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1575 Called by the \function{unistr()}\bifuncindex{unistr} built-in function.
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1576 \end{cfuncdesc}
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1577
17242
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1578 \begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1579 Return \code{1} if \var{inst} is an instance of the class \var{cls} or
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1580 a subclass of \var{cls}. If \var{cls} is a type object rather than a
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1581 class object, \cfunction{PyObject_IsInstance()} returns \code{1} if
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1582 \var{inst} is of type \var{cls}. If \var{inst} is not a class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1583 instance and \var{cls} is neither a type object or class object,
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1584 \var{inst} must have a \member{__class__} attribute --- the class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1585 relationship of the value of that attribute with \var{cls} will be
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1586 used to determine the result of this function.
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1587 \versionadded{2.1}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1588 \end{cfuncdesc}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1589
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1590 Subclass determination is done in a fairly straightforward way, but
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1591 includes a wrinkle that implementors of extensions to the class system
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1592 may want to be aware of. If \class{A} and \class{B} are class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1593 objects, \class{B} is a subclass of \class{A} if it inherits from
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1594 \class{A} either directly or indirectly. If either is not a class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1595 object, a more general mechanism is used to determine the class
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1596 relationship of the two objects. When testing if \var{B} is a
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1597 subclass of \var{A}, if \var{A} is \var{B},
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1598 \cfunction{PyObject_IsSubclass()} returns true. If \var{A} and
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1599 \var{B} are different objects, \var{B}'s \member{__bases__} attribute
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1600 is searched in a depth-first fashion for \var{A} --- the presence of
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1601 the \member{__bases__} attribute is considered sufficient for this
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1602 determination.
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1603
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1604 \begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived,
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1605 PyObject *cls}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1606 Returns \code{1} if the class \var{derived} is identical to or derived
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1607 from the class \var{cls}, otherwise returns \code{0}. In case of an
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1608 error, returns \code{-1}. If either \var{derived} or \var{cls} is not
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1609 an actual class object, this function uses the generic algorithm
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1610 described above.
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1611 \versionadded{2.1}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1612 \end{cfuncdesc}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1613
15952
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1614
5536
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}{PyCallable_Check}{PyObject *o}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1616 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
1617 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
1618 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
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
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1622 \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
1623 PyObject *args}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1624 Call a callable Python object \var{callable_object}, with
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1625 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
1626 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
1627 call on success, or \NULL{} on failure. This is the equivalent
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1628 of the Python expression \samp{apply(\var{callable_object}, \var{args})}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1629 \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
1630 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1631
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1632 \begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object,
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1633 char *format, ...}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1634 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
1635 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
1636 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
1637 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
1638 result of the call on success, or \NULL{} on failure. This is
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1639 the equivalent of the Python expression \samp{apply(\var{callable_object},
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1640 \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
1641 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1642
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1643
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1644 \begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o,
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1645 char *method, char *format, ...}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1646 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
1647 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
1648 \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
1649 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
1650 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
1651 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
1652 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
1653 \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
1654 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
1655 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1656
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1657
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1658 \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1659 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
1660 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
1661 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
1662 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1663
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1664
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1665 \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1666 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
1667 \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
1668 \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
1669 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
1670 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1671
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1672
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1673 \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
1674 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
1675 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
1676 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
1677 \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
1678 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1679
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1680 \begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1681 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
1682 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
1683 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
1684 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
1685 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1686
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1687
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1688 \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
1689 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
1690 \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
1691 \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
1692 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1693
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1694
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1695 \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
1696 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
1697 Returns \code{-1} on failure. This is the equivalent
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1698 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
1699 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1700
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1701
9931
00fc18ac6aeb Header for PyObject_DelItem() mentioned non-existing 3rd argument.
Guido van Rossum <guido@python.org>
parents: 9476
diff changeset
1702 \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
1703 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
1704 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
1705 \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
1706 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1707
13592
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1708 \begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o}
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1709 Derives a file-descriptor from a Python object. If the object
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1710 is an integer or long integer, its value is returned. If not, the
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1711 object's \method{fileno()} method is called if it exists; the method
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1712 must return an integer or long integer, which is returned as the file
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1713 descriptor value. Returns \code{-1} on failure.
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1714 \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
1715
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1716 \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
1717
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1718 \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1719 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
1720 false otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1721 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
1722 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1723
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1724
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1725 \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
1726 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
1727 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1728 \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
1729 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1730
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1731
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1732 \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
1733 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
1734 \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
1735 \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
1736 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1737
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1738
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1739 \begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1740 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
1741 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1742 \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
1743 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1744
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1745
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1746 \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
1747 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
1748 failure.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1749 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
1750 \var{o2}}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1751 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1752
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1753
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1754 \begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1755 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
1756 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
1757 \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
1758 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1759
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1760
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1761 \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
1762 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
1763 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
1764 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
1765 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1766
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1767
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1768 \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
1769 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
1770 \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
1771 \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
1772 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
1773 (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
1774 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1775
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1776
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1777 \begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1778 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
1779 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
1780 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1781
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1782
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1783 \begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1784 Returns \var{o} on success, or \NULL{} on failure.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1785 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
1786 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1787
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1788
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1789 \begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1790 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
1791 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
1792 \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
1793 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1794
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1795
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1796 \begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1797 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
1798 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1799 \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
1800 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1801
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1802
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1803 \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
1804 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
1805 or \NULL{} on failure. This is the equivalent of the Python
17480
04daee3ab627 Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents: 17336
diff changeset
1806 expression \samp{\var{o1} <\code{<} \var{o2}}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1807 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1808
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1809
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1810 \begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1811 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
1812 or \NULL{} on failure. This is the equivalent of the Python
17480
04daee3ab627 Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents: 17336
diff changeset
1813 expression \samp{\var{o1} >\code{>} \var{o2}}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1814 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1815
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1816
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1817 \begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1818 Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1819 \NULL{} on failure. This is the equivalent of the Python expression
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1820 \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
1821 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1822
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1823
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1824 \begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1825 Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on success,
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1826 or \NULL{} on failure. This is the equivalent of the Python
18576
7d77614fd0b7 Oops, one more caret.
Fred Drake <fdrake@acm.org>
parents: 18575
diff changeset
1827 expression \samp{\var{o1} \textasciicircum{} \var{o2}}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1828 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1829
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1830 \begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1831 Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1832 \NULL{} on failure. This is the equivalent of the Python expression
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1833 \samp{\var{o1} | \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1834 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1835
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1836
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1837 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1838 Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on failure.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1839 The operation is done \emph{in-place} when \var{o1} supports it. This is the
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1840 equivalent of the Python expression \samp{\var{o1} += \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1841 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1842
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1843
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1844 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1845 Returns the result of subtracting \var{o2} from \var{o1}, or
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1846 \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1847 supports it. This is the equivalent of the Python expression \samp{\var{o1}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1848 -= \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1849 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1850
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1851
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1852 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1853 Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1854 failure. The operation is done \emph{in-place} when \var{o1} supports it.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1855 This is the equivalent of the Python expression \samp{\var{o1} *= \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1856 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1857
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1858
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1859 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1860 Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on failure.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1861 The operation is done \emph{in-place} when \var{o1} supports it. This is the
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1862 equivalent of the Python expression \samp{\var{o1} /= \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1863 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1864
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1865
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1866 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1867 Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1868 failure. The operation is done \emph{in-place} when \var{o1} supports it.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1869 This is the equivalent of the Python expression \samp{\var{o1} \%= \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1870 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1871
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1872
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1873 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1, PyObject *o2, PyObject *o3}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1874 See the built-in function \function{pow()}\bifuncindex{pow}. Returns
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1875 \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1876 supports it. This is the equivalent of the Python expression \samp{\var{o1}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1877 **= \var{o2}} when o3 is \cdata{Py_None}, or an in-place variant of
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1878 \samp{pow(\var{o1}, \var{o2}, \var{o3})} otherwise. If \var{o3} is to be
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1879 ignored, pass \cdata{Py_None} in its place (passing \NULL{} for \var{o3}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1880 would cause an illegal memory access).
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1881 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1882
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1883 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1884 Returns the result of left shifting \var{o1} by \var{o2} on success, or
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1885 \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1886 supports it. This is the equivalent of the Python expression \samp{\var{o1}
17480
04daee3ab627 Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents: 17336
diff changeset
1887 <\code{<=} \var{o2}}.
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1888 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1889
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1890
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1891 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1892 Returns the result of right shifting \var{o1} by \var{o2} on success, or
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1893 \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1894 supports it. This is the equivalent of the Python expression \samp{\var{o1}
17480
04daee3ab627 Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents: 17336
diff changeset
1895 >\code{>=} \var{o2}}.
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1896 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1897
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1898
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1899 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2}
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1900 Returns the ``bitwise and'' of \var{o1} and \var{o2} on success
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1901 and \NULL{} on failure. The operation is done \emph{in-place} when
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1902 \var{o1} supports it. This is the equivalent of the Python expression
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1903 \samp{\var{o1} \&= \var{o2}}.
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1904 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1905
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1906
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1907 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1908 Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on success, or
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1909 \NULL{} on failure. The operation is done \emph{in-place} when \var{o1}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1910 supports it. This is the equivalent of the Python expression \samp{\var{o1}
18575
670464c94b92 Fix the markup of the caret charater in a couple of places; LaTeX's
Fred Drake <fdrake@acm.org>
parents: 18481
diff changeset
1911 \textasciicircum= \var{o2}}.
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1912 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1913
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1914 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1915 Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or \NULL{}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1916 on failure. The operation is done \emph{in-place} when \var{o1} supports
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1917 it. This is the equivalent of the Python expression \samp{\var{o1} |=
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1918 \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
1919 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1920
14769
aa18e5239b46 PyNumber_Coerce() returns an int, not a PyObject *.
Fred Drake <fdrake@acm.org>
parents: 14736
diff changeset
1921 \begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1922 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
1923 \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
1924 \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
1925 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
1926 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
1927 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
1928 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
1929 \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
1930 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
1931 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
1932 \bifuncindex{coerce}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1933 \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
1934
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1935 \begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1936 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
1937 \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
1938 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
1939 \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
1940
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1941 \begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1942 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
1943 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
1944 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
1945 \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
1946
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1947 \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
1948 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
1949 \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
1950 \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
1951 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1952
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1953
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1954 \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
1955
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1956 \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
1957 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
1958 \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
1959 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1960
17307
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents: 17242
diff changeset
1961 \begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1962 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
1963 \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
1964 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
1965 \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
1966 \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
1967
17307
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents: 17242
diff changeset
1968 \begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o}
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents: 17242
diff changeset
1969 Alternate name for \cfunction{PySequence_Size()}.
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents: 17242
diff changeset
1970 \end{cfuncdesc}
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents: 17242
diff changeset
1971
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1972 \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
1973 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
1974 failure. This is the equivalent of the Python
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1975 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
1976 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1977
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1978
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1979 \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
1980 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
1981 \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
1982 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
1983 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1984
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1985 \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1, PyObject *o2}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1986 Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1987 failure. The operation is done \emph{in-place} when \var{o1} supports it.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1988 This is the equivalent of the Python expression \samp{\var{o1} += \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1989 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1990
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1991
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1992 \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1993 Return the result of repeating sequence object \var{o} \var{count} times, or
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1994 \NULL{} on failure. The operation is done \emph{in-place} when \var{o}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1995 supports it. This is the equivalent of the Python expression \samp{\var{o}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1996 *= \var{count}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1997 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1998
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1999
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2000 \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
2001 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
2002 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
2003 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2004
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2005
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2006 \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
2007 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
2008 \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
2009 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
2010 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2011
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2012
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2013 \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
2014 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
2015 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
2016 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
2017 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2018
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2019 \begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
2020 Delete the \var{i}th element of object \var{o}. Returns
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2021 \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
2022 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
2023 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2024
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2025 \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
2026 int i2, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2027 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
2028 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
2029 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
2030 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2031
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2032 \begin{cfuncdesc}{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
2033 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
2034 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
2035 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
2036 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2037
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2038 \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2039 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
2040 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
2041 \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
2042 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2043
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2044 \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
2045 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
2046 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
2047 \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
2048 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
2049 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2050
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2051 \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
2052 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
2053 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
2054 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
2055 \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
2056 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2057
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2058 \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
2059 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
2060 \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
2061 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
2062 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2063
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2064 \begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2065 Return a list object with the same contents as the arbitrary sequence
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2066 \var{o}. The returned list is guaranteed to be new.
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2067 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2068
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2069 \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2070 Return a tuple object with the same contents as the arbitrary sequence
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2071 \var{o}. If \var{o} is a tuple, a new reference will be returned,
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2072 otherwise a tuple will be constructed with the appropriate contents.
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2073 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2074
7493
6857acbe2e74 Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7467
diff changeset
2075
14519
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2076 \begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2077 Returns the sequence \var{o} as a tuple, unless it is already a
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2078 tuple or list, in which case \var{o} is returned. Use
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2079 \cfunction{PySequence_Fast_GET_ITEM()} to access the members of the
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2080 result. Returns \NULL{} on failure. If the object is not a sequence,
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2081 raises \exception{TypeError} with \var{m} as the message text.
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2082 \end{cfuncdesc}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2083
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2084 \begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2085 Return the \var{i}th element of \var{o}, assuming that \var{o} was
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2086 returned by \cfunction{PySequence_Fast()}, and that \var{i} is within
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2087 bounds. The caller is expected to get the length of the sequence by
18000
ec9343ad1e60 Users of PySequence_GET_FAST() should get the length of the sequence using
Fred Drake <fdrake@acm.org>
parents: 17981
diff changeset
2088 calling \cfunction{PySequence_Size()} on \var{o}, since lists and tuples
14519
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2089 are guaranteed to always return their true length.
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2090 \end{cfuncdesc}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2091
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2092
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2093 \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
2094
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2095 \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
2096 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
2097 \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
2098 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2099
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2100
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2101 \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
2102 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
2103 \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
2104 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
2105 \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
2106 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2107
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2108
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2109 \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
2110 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
2111 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2112 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
2113 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2114
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2115
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2116 \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
2117 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
2118 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2119 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
2120 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2121
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2122
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2123 \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
2124 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
2125 \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
2126 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
2127 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
2128 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2129
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2130
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2131 \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
2132 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
2133 \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
2134 \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
2135 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
2136 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2137
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2138
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2139 \begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2140 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
2141 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
2142 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
2143 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2144
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2145
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2146 \begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2147 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
2148 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
2149 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
2150 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2151
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2152
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2153 \begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2154 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
2155 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
2156 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
2157 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
2158 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2159
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2160
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2161 \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
2162 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
2163 \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
2164 \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
2165 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2166
17695
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2167 \begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key,
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2168 PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2169 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
2170 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
2171 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
2172 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2173
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2174
17695
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2175 \section{Iterator Protocol \label{iterator}}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2176
17696
ffc2923bad1a Hmm... better add a version annotation for the Iterator Protocol section.
Fred Drake <fdrake@acm.org>
parents: 17695
diff changeset
2177 \versionadded{2.2}
ffc2923bad1a Hmm... better add a version annotation for the Iterator Protocol section.
Fred Drake <fdrake@acm.org>
parents: 17695
diff changeset
2178
17695
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2179 There are only a couple of functions specifically for working with
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2180 iterators.
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2181
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2182 \begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2183 Return true if the object \var{o} supports the iterator protocol.
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2184 \end{cfuncdesc}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2185
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2186 \begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2187 Return the next value from the iteration \var{o}. If the object is
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2188 an iterator, this retrieves the next value from the iteration, and
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2189 returns \NULL{} with no exception set if there are no remaining
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2190 items. If the object is not an iterator, \exception{TypeError} is
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2191 raised, or if there is an error in retrieving the item, returns
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2192 \NULL{} and passes along the exception.
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2193 \end{cfuncdesc}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2194
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2195 To write a loop which iterates over an iterator, the C code should
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2196 look something like this:
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2197
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2198 \begin{verbatim}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2199 PyObject *iterator = ...;
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2200 PyObject *item;
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2201
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2202 while (item = PyIter_Next(iter)) {
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2203 /* do something with item */
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2204 }
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2205 if (PyErr_Occurred()) {
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2206 /* propogate error */
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2207 }
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2208 else {
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2209 /* continue doing useful work */
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2210 }
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2211 \end{verbatim}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2212
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2213
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2214 \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
2215
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2216 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
2217 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
2218 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
2219 that it has the right type, you must perform a type check first;
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
2220 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
2221 \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
2222 ``family tree'' of Python object types.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2223
15300
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2224 \strong{Warning:}
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2225 While the functions described in this chapter carefully check the type
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2226 of the objects which are passed in, many of them do not check for
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2227 \NULL{} being passed instead of a valid object. Allowing \NULL{} to
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2228 be passed in can cause memory access violations and immediate
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2229 termination of the interpreter.
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2230
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2231
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2232 \section{Fundamental Objects \label{fundamental}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2233
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2234 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
2235 \code{None}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2236
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2237
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2238 \subsection{Type Objects \label{typeObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2239
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2240 \obindex{type}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2241 \begin{ctypedesc}{PyTypeObject}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2242 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
2243 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2244
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2245 \begin{cvardesc}{PyObject*}{PyType_Type}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2246 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
2247 \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
2248 \withsubitem{(in module types)}{\ttindex{TypeType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2249 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2250
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2251 \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
2252 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
2253 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2254
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2255 \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
2256 Returns true if the type object \var{o} sets the feature
16439
d557ff0a2f6c Remove an now-false statement about there being only one type flag
Fred Drake <fdrake@acm.org>
parents: 16318
diff changeset
2257 \var{feature}. Type features are denoted by single bit flags.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2258 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2259
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2260
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2261 \subsection{The None Object \label{noneObject}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2262
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2263 \obindex{None@\texttt{None}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2264 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
2265 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
2266 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
2267 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
2268
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2269 \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
2270 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
2271 no methods.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2272 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2273
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2274
18481
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2275 \section{Numeric Objects \label{numericObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2276
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2277 \obindex{numeric}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2278
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2279
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2280 \subsection{Plain Integer Objects \label{intObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2281
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2282 \obindex{integer}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2283 \begin{ctypedesc}{PyIntObject}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2284 This subtype of \ctype{PyObject} represents a Python integer object.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2285 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2286
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2287 \begin{cvardesc}{PyTypeObject}{PyInt_Type}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2288 This instance of \ctype{PyTypeObject} represents the Python plain
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2289 integer type. This is the same object as \code{types.IntType}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2290 \withsubitem{(in modules types)}{\ttindex{IntType}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2291 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2292
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2293 \begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2294 Returns true if \var{o} is of type \cdata{PyInt_Type}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2295 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2296
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2297 \begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2298 Creates a new integer object with a value of \var{ival}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2299
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2300 The current implementation keeps an array of integer objects for all
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2301 integers between \code{-1} and \code{100}, when you create an int in
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2302 that range you actually just get back a reference to the existing
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2303 object. So it should be possible to change the value of \code{1}. I
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2304 suspect the behaviour of Python in this case is undefined. :-)
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2305 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2306
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2307 \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2308 Will first attempt to cast the object to a \ctype{PyIntObject}, if
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2309 it is not already one, and then return its value.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2310 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2311
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2312 \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2313 Returns the value of the object \var{io}. No error checking is
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2314 performed.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2315 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2316
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2317 \begin{cfuncdesc}{long}{PyInt_GetMax}{}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2318 Returns the system's idea of the largest integer it can handle
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2319 (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2320 header files).
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2321 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2322
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2323
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2324 \subsection{Long Integer Objects \label{longObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2325
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2326 \obindex{long integer}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2327 \begin{ctypedesc}{PyLongObject}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2328 This subtype of \ctype{PyObject} represents a Python long integer
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2329 object.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2330 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2331
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2332 \begin{cvardesc}{PyTypeObject}{PyLong_Type}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2333 This instance of \ctype{PyTypeObject} represents the Python long
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2334 integer type. This is the same object as \code{types.LongType}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2335 \withsubitem{(in modules types)}{\ttindex{LongType}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2336 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2337
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2338 \begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2339 Returns true if its argument is a \ctype{PyLongObject}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2340 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2341
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2342 \begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2343 Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{} on
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2344 failure.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2345 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2346
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2347 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2348 Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2349 long}, or \NULL{} on failure.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2350 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2351
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2352 \begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2353 Returns a new \ctype{PyLongObject} object from the integer part of
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2354 \var{v}, or \NULL{} on failure.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2355 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2356
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2357 \begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2358 Returns a C \ctype{long} representation of the contents of
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2359 \var{pylong}. If \var{pylong} is greater than
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2360 \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2361 raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2362 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2363
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2364 \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2365 Returns a C \ctype{unsigned long} representation of the contents of
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2366 \var{pylong}. If \var{pylong} is greater than
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2367 \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2368 is raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2369 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2370
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2371 \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2372 Returns a C \ctype{double} representation of the contents of \var{pylong}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2373 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2374
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2375 \begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend,
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2376 int base}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2377 Return a new \ctype{PyLongObject} based on the string value in
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2378 \var{str}, which is interpreted according to the radix in \var{base}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2379 If \var{pend} is non-\NULL, \code{*\var{pend}} will point to the first
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2380 character in \var{str} which follows the representation of the
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2381 number. If \var{base} is \code{0}, the radix will be determined base
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2382 on the leading characters of \var{str}: if \var{str} starts with
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2383 \code{'0x'} or \code{'0X'}, radix 16 will be used; if \var{str} starts
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2384 with \code{'0'}, radix 8 will be used; otherwise radix 10 will be
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2385 used. If \var{base} is not \code{0}, it must be between \code{2} and
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2386 \code{36}, inclusive. Leading spaces are ignored. If there are no
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2387 digits, \exception{ValueError} will be raised.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2388 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2389
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2390
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2391 \subsection{Floating Point Objects \label{floatObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2392
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2393 \obindex{floating point}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2394 \begin{ctypedesc}{PyFloatObject}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2395 This subtype of \ctype{PyObject} represents a Python floating point
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2396 object.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2397 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2398
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2399 \begin{cvardesc}{PyTypeObject}{PyFloat_Type}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2400 This instance of \ctype{PyTypeObject} represents the Python floating
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2401 point type. This is the same object as \code{types.FloatType}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2402 \withsubitem{(in modules types)}{\ttindex{FloatType}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2403 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2404
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2405 \begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2406 Returns true if its argument is a \ctype{PyFloatObject}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2407 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2408
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2409 \begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2410 Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2411 failure.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2412 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2413
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2414 \begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2415 Returns a C \ctype{double} representation of the contents of \var{pyfloat}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2416 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2417
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2418 \begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2419 Returns a C \ctype{double} representation of the contents of
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2420 \var{pyfloat}, but without error checking.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2421 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2422
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2423
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2424 \subsection{Complex Number Objects \label{complexObjects}}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2425
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2426 \obindex{complex number}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2427 Python's complex number objects are implemented as two distinct types
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2428 when viewed from the C API: one is the Python object exposed to
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2429 Python programs, and the other is a C structure which represents the
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2430 actual complex number value. The API provides functions for working
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2431 with both.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2432
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2433 \subsubsection{Complex Numbers as C Structures}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2434
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2435 Note that the functions which accept these structures as parameters
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2436 and return them as results do so \emph{by value} rather than
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2437 dereferencing them through pointers. This is consistent throughout
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2438 the API.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2439
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2440 \begin{ctypedesc}{Py_complex}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2441 The C structure which corresponds to the value portion of a Python
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2442 complex number object. Most of the functions for dealing with complex
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2443 number objects use structures of this type as input or output values,
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2444 as appropriate. It is defined as:
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2445
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2446 \begin{verbatim}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2447 typedef struct {
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2448 double real;
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2449 double imag;
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2450 } Py_complex;
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2451 \end{verbatim}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2452 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2453
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2454 \begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2455 Return the sum of two complex numbers, using the C
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2456 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2457 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2458
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2459 \begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2460 Return the difference between two complex numbers, using the C
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2461 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2462 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2463
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2464 \begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2465 Return the negation of the complex number \var{complex}, using the C
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2466 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2467 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2468
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2469 \begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2470 Return the product of two complex numbers, using the C
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2471 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2472 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2473
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2474 \begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend,
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2475 Py_complex divisor}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2476 Return the quotient of two complex numbers, using the C
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2477 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2478 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2479
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2480 \begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2481 Return the exponentiation of \var{num} by \var{exp}, using the C
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2482 \ctype{Py_complex} representation.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2483 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2484
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2485
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2486 \subsubsection{Complex Numbers as Python Objects}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2487
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2488 \begin{ctypedesc}{PyComplexObject}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2489 This subtype of \ctype{PyObject} represents a Python complex number object.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2490 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2491
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2492 \begin{cvardesc}{PyTypeObject}{PyComplex_Type}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2493 This instance of \ctype{PyTypeObject} represents the Python complex
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2494 number type.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2495 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2496
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2497 \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2498 Returns true if its argument is a \ctype{PyComplexObject}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2499 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2500
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2501 \begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2502 Create a new Python complex number object from a C
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2503 \ctype{Py_complex} value.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2504 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2505
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2506 \begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2507 Returns a new \ctype{PyComplexObject} object from \var{real} and \var{imag}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2508 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2509
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2510 \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2511 Returns the real part of \var{op} as a C \ctype{double}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2512 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2513
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2514 \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2515 Returns the imaginary part of \var{op} as a C \ctype{double}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2516 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2517
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2518 \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2519 Returns the \ctype{Py_complex} value of the complex number \var{op}.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2520 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2521
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2522
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2523
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2524 \section{Sequence Objects \label{sequenceObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2525
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2526 \obindex{sequence}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2527 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
2528 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
2529 objects that are intrinsic to the Python language.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2530
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2531
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2532 \subsection{String Objects \label{stringObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2533
15300
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2534 These functions raise \exception{TypeError} when expecting a string
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2535 parameter and are called with a non-string parameter.
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2536
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2537 \obindex{string}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2538 \begin{ctypedesc}{PyStringObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
2539 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
2540 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2541
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2542 \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
2543 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
2544 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
2545 layer.\withsubitem{(in module types)}{\ttindex{StringType}}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2546 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2547
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2548 \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
2549 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
2550 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2551
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2552 \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
2553 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
2554 \NULL{} on failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2555 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2556
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2557 \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
2558 int len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2559 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
2560 \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
2561 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
2562 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2563
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2564 \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
2565 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
2566 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2567
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2568 \begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string}
15087
a13a2acbe214 Fix a couple of places where the descriptions of *_GET_SIZE() macros said
Fred Drake <fdrake@acm.org>
parents: 15038
diff changeset
2569 Macro form of \cfunction{PyString_Size()} but without error
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2570 checking.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2571 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2572
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2573 \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
2574 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
2575 \var{string}. The pointer refers to the internal buffer of
15300
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2576 \var{string}, not a copy. The data must not be modified in any way,
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2577 unless the string was just created using
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2578 \code{PyString_FromStringAndSize(NULL, \var{size})}.
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2579 It must not be deallocated.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2580 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2581
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2582 \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
2583 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
2584 checking.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2585 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2586
14696
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2587 \begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj,
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2588 char **buffer,
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2589 int *length}
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2590 Returns a null-terminated representation of the contents of the object
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2591 \var{obj} through the output variables \var{buffer} and \var{length}.
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2592
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2593 The function accepts both string and Unicode objects as input. For
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2594 Unicode objects it returns the default encoded version of the object.
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2595 If \var{length} is set to \NULL{}, the resulting buffer may not contain
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2596 null characters; if it does, the function returns -1 and a
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2597 TypeError is raised.
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2598
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2599 The buffer refers to an internal string buffer of \var{obj}, not a
15300
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2600 copy. The data must not be modified in any way, unless the string was
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2601 just created using \code{PyString_FromStringAndSize(NULL,
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2602 \var{size})}. It must not be deallocated.
14696
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2603 \end{cfuncdesc}
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2604
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2605 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2606 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
2607 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
2608 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
2609 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
2610 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
2611 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
2612 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
2613 \NULL{}; the appropriate exception will be set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2614 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2615
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2616 \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2617 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
2618 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
2619 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
2620 the reference count of \var{newpart}.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2621 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2622
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2623 \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
2624 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
2625 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
2626 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
2627 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2628
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2629 \begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2630 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
2631 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
2632 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
2633 a tuple.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2634 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2635
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2636 \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
2637 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
2638 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
2639 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
2640 \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
2641 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
2642 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
2643 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
2644 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
2645 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
2646 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
2647 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2648
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2649 \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
2650 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
2651 \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
2652 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
2653 interned string object with the same value.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2654 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2655
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2656 \begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2657 int size,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2658 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2659 const char *errors}
17835
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2660 Creates an object by decoding \var{size} bytes of the encoded
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2661 buffer \var{s} using the codec registered
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2662 for \var{encoding}. \var{encoding} and \var{errors} have the same meaning
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2663 as the parameters of the same name in the unicode() builtin
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2664 function. The codec to be used is looked up using the Python codec
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2665 registry. Returns \NULL{} in case an exception was raised by the
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2666 codec.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2667 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2668
17835
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2669 \begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str,
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2670 const char *encoding,
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2671 const char *errors}
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2672 Decodes a string object by passing it to the codec registered
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2673 for \var{encoding} and returns the result as Python
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2674 object. \var{encoding} and \var{errors} have the same meaning as the
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2675 parameters of the same name in the string .encode() method. The codec
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2676 to be used is looked up using the Python codec registry. Returns
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2677 \NULL{} in case an exception was raised by the codec.
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2678 \end{cfuncdesc}
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2679
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2680 \begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s,
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2681 int size,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2682 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2683 const char *errors}
17835
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2684 Encodes the \ctype{char} buffer of the given size by passing it to
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2685 the codec registered for \var{encoding} and returns a Python object.
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2686 \var{encoding} and \var{errors} have the same
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2687 meaning as the parameters of the same name in the string .encode()
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2688 method. The codec to be used is looked up using the Python codec
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2689 registry. Returns \NULL{} in case an exception was raised by the
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2690 codec.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2691 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2692
17835
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2693 \begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str,
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2694 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2695 const char *errors}
17835
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2696 Encodes a string object using the codec registered
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2697 for \var{encoding} and returns the result as Python
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2698 object. \var{encoding} and \var{errors} have the same meaning as the
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2699 parameters of the same name in the string .encode() method. The codec
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2700 to be used is looked up using the Python codec registry. Returns
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2701 \NULL{} in case an exception was raised by the codec.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2702 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2703
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2704
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2705 \subsection{Unicode Objects \label{unicodeObjects}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2706 \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2707
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2708 %--- Unicode Type -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2709
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2710 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
2711 implementation in Python:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2712
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2713 \begin{ctypedesc}{Py_UNICODE}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2714 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
2715 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
2716 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
2717 \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
2718 native platform compatibility. On all other platforms,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2719 \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
2720 \end{ctypedesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2721
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2722 \begin{ctypedesc}{PyUnicodeObject}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2723 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
2724 \end{ctypedesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2725
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2726 \begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2727 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
2728 \end{cvardesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2729
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2730 %--- 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
2731
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2732 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
2733 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
2734
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2735 \begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2736 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
2737 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2738
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2739 \begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2740 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
2741 PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2742 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2743
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2744 \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
2745 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
2746 a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2747 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2748
12932
1fa7c119b7a5 Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support.
Fred Drake <fdrake@acm.org>
parents: 12930
diff changeset
2749 \begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2750 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
2751 has to be a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2752 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2753
12932
1fa7c119b7a5 Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support.
Fred Drake <fdrake@acm.org>
parents: 12930
diff changeset
2754 \begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2755 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
2756 o has to be a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2757 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2758
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2759 % --- Unicode character properties ---------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2760
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2761 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
2762 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
2763 functions depending on the Python configuration.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2764
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2765 \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
2766 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
2767 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2768
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2769 \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
2770 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
2771 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2772
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2773 \begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch}
13321
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2774 Returns 1/0 depending on whether \var{ch} is an uppercase character.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2775 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2776
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2777 \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
2778 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
2779 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2780
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2781 \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
2782 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
2783 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2784
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2785 \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
2786 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
2787 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2788
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2789 \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
2790 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
2791 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2792
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2793 \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
2794 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
2795 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2796
13321
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2797 \begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2798 Returns 1/0 depending on whether \var{ch} is an alphabetic character.
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2799 \end{cfuncdesc}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2800
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2801 \begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2802 Returns 1/0 depending on whether \var{ch} is an alphanumeric character.
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2803 \end{cfuncdesc}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
2804
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2805 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
2806
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2807 \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
2808 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
2809 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2810
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2811 \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
2812 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
2813 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2814
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2815 \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
2816 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
2817 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2818
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2819 \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
2820 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
2821 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
2822 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2823
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2824 \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
2825 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
2826 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
2827 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2828
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2829 \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
2830 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
2831 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
2832 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2833
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2834 % --- Plain Py_UNICODE ---------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2835
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2836 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
2837 use these APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2838
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2839 \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
2840 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2841
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2842 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
2843 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
2844 undefined. It is the user's responsibility to fill in the needed data.
17618
b44ba7c01217 This patch originated from an idea by Martin v. Loewis who submitted a
Marc-André Lemburg <mal@egenix.com>
parents: 17504
diff changeset
2845 The buffer is copied into the new object. If the buffer is not \NULL{},
b44ba7c01217 This patch originated from an idea by Martin v. Loewis who submitted a
Marc-André Lemburg <mal@egenix.com>
parents: 17504
diff changeset
2846 the return value might be a shared object. Therefore, modification of
b44ba7c01217 This patch originated from an idea by Martin v. Loewis who submitted a
Marc-André Lemburg <mal@egenix.com>
parents: 17504
diff changeset
2847 the resulting Unicode Object is only allowed when \var{u} is \NULL{}.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2848 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2849
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
2850 \begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2851 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
2852 \ctype{Py_UNICODE} buffer.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2853 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2854
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2855 \begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2856 Return the length of the Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2857 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2858
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2859 \begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2860 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2861 const char *errors}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2862
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2863 Coerce an encoded object obj to an Unicode object and return a
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2864 reference with incremented refcount.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2865
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2866 Coercion is done in the following way:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2867 \begin{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2868 \item Unicode objects are passed back as-is with incremented
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2869 refcount. Note: these cannot be decoded; passing a non-NULL
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2870 value for encoding will result in a TypeError.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2871
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2872 \item String and other char buffer compatible objects are decoded
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2873 according to the given encoding and using the error handling
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2874 defined by errors. Both can be NULL to have the interface use
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2875 the default values (see the next section for details).
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2876
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2877 \item All other objects cause an exception.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2878 \end{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2879 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
2880 for decref'ing the returned objects.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2881 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2882
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2883 \begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2884
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2885 Shortcut for PyUnicode_FromEncodedObject(obj, NULL, ``strict'')
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2886 which is used throughout the interpreter whenever coercion to
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2887 Unicode is needed.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2888 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2889
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2890 % --- wchar_t support for platforms which support it ---------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2891
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2892 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
2893 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
2894 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
2895 \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
2896
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2897 \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
2898 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2899 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
2900 given size. Returns \NULL{} on failure.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2901 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2902
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2903 \begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2904 wchar_t *w,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2905 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2906 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
2907 \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
2908 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
2909 of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2910 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2911
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2912
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2913 \subsubsection{Builtin Codecs \label{builtinCodecs}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2914
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2915 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
2916 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
2917 following functions.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2918
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2919 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
2920 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
2921 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
2922
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2923 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
2924 is UTF-8.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2925
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2926 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
2927 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
2928 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
2929
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2930 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
2931 following generic ones are documented for simplicity.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2932
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2933 % --- Generic Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2934
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2935 These are the generic codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2936
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2937 \begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2938 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2939 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2940 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2941 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
2942 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
2943 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
2944 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
2945 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
2946 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2947 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2948
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2949 \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
2950 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2951 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2952 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2953 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
2954 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
2955 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
2956 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
2957 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
2958 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2959 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2960
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2961 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2962 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2963 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2964 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
2965 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
2966 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
2967 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
2968 \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
2969 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2970
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2971 % --- UTF-8 Codecs -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2972
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2973 These are the UTF-8 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2974
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2975 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2976 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2977 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2978 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
2979 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
2980 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2981 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2982
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2983 \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
2984 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2985 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2986 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
2987 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
2988 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2989 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2990
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2991 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2992 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
2993 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2994 \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
2995 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2996
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2997 % --- UTF-16 Codecs ------------------------------------------------------ */
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2998
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2999 These are the UTF-16 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3000
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3001 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3002 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3003 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3004 int *byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3005 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
3006 returns the corresponding Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3007
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3008 \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
3009 to ``strict''.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3010
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3011 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
3012 the given byte order:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3013
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3014 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3015 *byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3016 *byteorder == 0: native order
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3017 *byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3018 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3019
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3020 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
3021 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
3022 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
3023 order at the end of input data.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3024
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3025 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
3026
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3027 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
3028 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3029
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3030 \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
3031 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3032 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3033 int byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3034 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
3035 Unicode data in \var{s}.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3036
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
3037 If \var{byteorder} is not \code{0}, output is written according to the
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3038 following byte order:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3039
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3040 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3041 byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3042 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
3043 byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3044 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3045
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
3046 If byteorder is \code{0}, the output string will always start with the
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3047 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
3048 prepended.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3049
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3050 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
3051 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
3052 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
3053
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3054 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
3055 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3056
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3057 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3058 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
3059 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
3060 ``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
3061 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3062 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3063
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3064 % --- Unicode-Escape Codecs ----------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3065
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3066 These are the ``Unicode Esacpe'' codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3067
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3068 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3069 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3070 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3071 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
3072 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
3073 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3074 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3075
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3076 \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
3077 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3078 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3079 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
3080 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
3081 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3082 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3083
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3084 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3085 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
3086 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
3087 \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
3088 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3089
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3090 % --- Raw-Unicode-Escape Codecs ------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3091
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3092 These are the ``Raw Unicode Esacpe'' codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3093
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3094 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3095 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3096 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3097 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
3098 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
3099 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3100 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3101
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3102 \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
3103 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3104 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3105 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
3106 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
3107 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3108 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3109
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3110 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3111 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
3112 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
3113 \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
3114 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3115
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3116 % --- Latin-1 Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3117
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3118 These are the Latin-1 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3119
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3120 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
3121 are accepted by the codecs during encoding.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3122
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3123 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3124 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3125 const char *errors}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3126 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
3127 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
3128 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3129 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3130
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3131 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3132 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3133 const char *errors}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3134 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
3135 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
3136 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3137 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3138
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3139 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3140 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
3141 Python string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3142 \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
3143 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3144
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3145 % --- ASCII Codecs -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3146
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3147 These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3148 accepted. All other codes generate errors.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3149
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3150 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3151 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3152 const char *errors}
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3153 Creates a Unicode object by decoding \var{size} bytes of the
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3154 \ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3155 was raised by the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3156 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3157
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3158 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3159 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3160 const char *errors}
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3161 Encodes the \ctype{Py_UNICODE} buffer of the given size using
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3162 \ASCII{} and returns a Python string object. Returns \NULL{} in case
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3163 an exception was raised by the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3164 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3165
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3166 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3167 Encodes a Unicode objects using \ASCII{} and returns the result as Python
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3168 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3169 \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
3170 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3171
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3172 % --- Character Map Codecs -----------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3173
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3174 These are the mapping codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3175
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3176 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
3177 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
3178 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
3179 codec uses mapping to encode and decode characters.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3180
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3181 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
3182 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
3183 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
3184
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3185 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
3186 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
3187 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
3188
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3189 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
3190 interface.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3191
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3192 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
3193 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
3194 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
3195 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
3196 points.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3197
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3198 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3199 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3200 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3201 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3202 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
3203 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
3204 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
3205 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3206
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3207 \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
3208 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3209 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3210 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3211 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
3212 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
3213 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
3214 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3215
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3216 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3217 PyObject *mapping}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3218 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
3219 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
3220 ``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
3221 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3222 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3223
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3224 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
3225
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3226 \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
3227 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3228 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3229 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3230 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
3231 a character mapping \var{table} to it and returns the resulting
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3232 Unicode object. Returns \NULL{} when an exception was raised by the
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3233 codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3234
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3235 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
3236 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
3237
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3238 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3239 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
3240 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
3241 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3242
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3243 % --- MBCS codecs for Windows --------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3244
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3245 These are the MBCS codec APIs. They are currently only available on
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3246 Windows and use the Win32 MBCS converters to implement the
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3247 conversions. Note that MBCS (or DBCS) is a class of encodings, not
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3248 just one. The target encoding is defined by the user settings on the
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3249 machine running the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3250
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3251 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3252 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3253 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3254 Creates a Unicode object by decoding \var{size} bytes of the MBCS
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3255 encoded string \var{s}. Returns \NULL{} in case an exception was
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3256 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3257 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3259 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3260 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3261 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3262 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
3263 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
3264 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3265 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3266
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3267 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3268 Encodes a Unicode objects using MBCS and returns the result as Python
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3269 string object. Error handling is ``strict''. Returns \NULL{} in case
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3270 an exception was raised by the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3271 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3272
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3273 % --- Methods & Slots ----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3274
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3275 \subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3276
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3277 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
3278 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
3279 Unicode objects or integers as apporpriate.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3280
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3281 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
3282
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3283 \begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3284 PyObject *right}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3285 Concat two strings giving a new Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3286 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3287
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3288 \begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3289 PyObject *sep,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3290 int maxsplit}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3291 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
3292
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3293 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
3294 substrings. Otherwise, splits occur at the given separator.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3295
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3296 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
3297
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3298 Separators are not included in the resulting list.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3299 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3300
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3301 \begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3302 int maxsplit}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3303 Split a Unicode string at line breaks, returning a list of Unicode
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3304 strings. CRLF is considered to be one line break. The Line break
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3305 characters are not included in the resulting strings.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3306 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3307
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3308 \begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3309 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3310 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3311 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
3312 return the resulting Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3313
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3314 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
3315 integers or None (causing deletion of the character).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3316
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3317 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3318 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
3319 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
3320
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3321 \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
3322 which indicates to use the default error handling.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3323 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3324
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3325 \begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3326 PyObject *seq}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3327 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
3328 the resulting Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3329 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3330
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3331 \begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3332 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3333 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3334 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3335 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3336 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
3337 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
3338 \var{direction} == 1 a suffix match), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3339 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3340
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3341 \begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3342 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3343 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3344 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3345 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3346 Return the first position of \var{substr} in
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3347 \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
3348 (\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
3349 \var{direction} == -1 a backward search), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3350 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3351
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3352 \begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3353 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3354 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3355 int end}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3356 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
3357 \var{str}[\var{start}:\var{end}]
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3358 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3359
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3360 \begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3361 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3362 PyObject *replstr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3363 int maxcount}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3364 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
3365 \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
3366 \var{maxcount} == -1 means: replace all occurrences.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3367 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3368
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3369 \begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3370 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
3371 greater than resp.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3372 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3373
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3374 \begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3375 PyObject *args}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3376 Returns a new string object from \var{format} and \var{args}; this is
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3377 analogous to \code{\var{format} \%\ \var{args}}. The
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3378 \var{args} argument must be a tuple.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3379 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3380
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3381 \begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3382 PyObject *element}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3383 Checks whether \var{element} is contained in \var{container} and
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3384 returns true or false accordingly.
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3385
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3386 \var{element} has to coerce to a one element Unicode string. \code{-1} is
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3387 returned in case of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3388 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3389
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3390
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3391 \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
3392 \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
3393
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3394 \obindex{buffer}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3395 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
3396 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
3397 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
3398 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
3399 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
3400
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3401 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
3402 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
3403 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
3404 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
3405 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
3406
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3407 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
3408 \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
3409 through the buffer interface can be written to a file. There are a
18785
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
3410 number of format codes to \cfunction{PyArg_ParseTuple()} that operate
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3411 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
3412 object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3413
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3414 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
3415 ``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
3416 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
3417
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3418 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
3419 (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
3420 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
3421 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
3422 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
3423 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
3424 interface.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3425
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3426 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
3427 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
3428 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
3429 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
3430 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
3431 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
3432 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
3433 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
3434 format.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3435
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3436 \begin{ctypedesc}{PyBufferObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3437 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
3438 \end{ctypedesc}
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3439
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3440 \begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3441 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
3442 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
3443 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
3444 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3445
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3446 \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
3447 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
3448 \cfunction{PyBuffer_FromObject()} or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3449 \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
3450 \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
3451 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
3452 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
3453 length.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3454 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3455
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3456 \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
3457 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
3458 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3459
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3460 \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
3461 int offset, int size}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3462 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
3463 \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
3464 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
3465 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
3466 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
3467 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
3468 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
3469 \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
3470 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
3471 \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
3472 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3473
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3474 \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
3475 int offset,
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3476 int size}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3477 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
3478 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
3479 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
3480 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
3481 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3482
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3483 \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
3484 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
3485 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
3486 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
3487 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
3488 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
3489 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
3490 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
3491 that case.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3492 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3493
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3494 \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
3495 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
3496 is writable.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3497 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3498
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3499 \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
3500 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
3501 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
3502 \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
3503 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3504
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3505
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3506 \subsection{Tuple Objects \label{tupleObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3507
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3508 \obindex{tuple}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3509 \begin{ctypedesc}{PyTupleObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3510 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
3511 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3512
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3513 \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
3514 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
3515 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
3516 layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3517 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3518
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3519 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3520 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
3521 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3522
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3523 \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
3524 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
3525 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3526
16577
068cb8494b7b PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents: 16439
diff changeset
3527 \begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3528 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
3529 of that tuple.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3530 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3531
16577
068cb8494b7b PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents: 16439
diff changeset
3532 \begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3533 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
3534 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
3535 sets an \exception{IndexError} exception.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3536 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3537
16577
068cb8494b7b PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents: 16439
diff changeset
3538 \begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos}
17981
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3539 Like \cfunction{PyTuple_GetItem()}, but does no checking of its
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3540 arguments.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3541 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3542
16577
068cb8494b7b PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents: 16439
diff changeset
3543 \begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p,
068cb8494b7b PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents: 16439
diff changeset
3544 int low, int high}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3545 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
3546 \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
3547 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3548
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3549 \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
3550 int pos, PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3551 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
3552 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
3553 \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
3554 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3555
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3556 \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
3557 int pos, PyObject *o}
17981
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3558 Like \cfunction{PyTuple_SetItem()}, but does no error checking, and
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3559 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
3560 \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
3561 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3562
17981
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3563 \begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3564 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
3565 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
3566 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
3567 Do \emph{not} use this if the tuple may already be known to some other
17981
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3568 part of the code. The tuple will always grow or shrink at the end.
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3569 Think of this as destroying the old tuple and creating a new one, only
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3570 more efficiently. Returns \code{0} on success. Client code should
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3571 never assume that the resulting value of \code{*\var{p}} will be the
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3572 same as before calling this function. If the object referenced by
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3573 \code{*\var{p}} is replaced, the original \code{*\var{p}} is
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3574 destroyed. On failure, returns \code{-1} and sets \code{*\var{p}} to
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3575 \NULL, and raises \exception{MemoryError} or \exception{SystemError}.
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3576 \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3577 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3578
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3579
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3580 \subsection{List Objects \label{listObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3581
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3582 \obindex{list}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3583 \begin{ctypedesc}{PyListObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3584 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
3585 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3586
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3587 \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
3588 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
3589 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
3590 \withsubitem{(in module types)}{\ttindex{ListType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3591 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3592
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3593 \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
3594 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
3595 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3596
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3597 \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
3598 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
3599 failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3600 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3601
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3602 \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
3603 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
3604 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
3605 \bifuncindex{len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3606 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3607
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3608 \begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
15087
a13a2acbe214 Fix a couple of places where the descriptions of *_GET_SIZE() macros said
Fred Drake <fdrake@acm.org>
parents: 15038
diff changeset
3609 Macro form of \cfunction{PyList_Size()} without error checking.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3610 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3611
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3612 \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
3613 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
3614 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
3615 sets an \exception{IndexError} exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3616 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3617
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3618 \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
3619 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
3620 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3621
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3622 \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3623 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
3624 Sets the item at index \var{index} in list to \var{item}.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3625 Returns \code{0} on success or \code{-1} on failure.
18020
e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 18000
diff changeset
3626 \strong{Note:} This function ``steals'' a reference to \var{item} and
e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 18000
diff changeset
3627 discards a reference to an item already in the list at the affected
e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 18000
diff changeset
3628 position.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3629 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3630
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3631 \begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i,
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3632 PyObject *o}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3633 Macro form of \cfunction{PyList_SetItem()} without error checking.
18020
e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 18000
diff changeset
3634 \strong{Note:} This function ``steals'' a reference to \var{item},
e86d33081bba Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 18000
diff changeset
3635 and, unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3636 reference to any item that it being replaced; any reference in
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3637 \var{list} at position \var{i} will be leaked. This is normally only
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3638 used to fill in new lists where there is no previous content.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3639 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3640
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3641 \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
3642 PyObject *item}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3643 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
3644 \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
3645 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
3646 \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
3647 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3648
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3649 \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
3650 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
3651 \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
3652 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
3653 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3654
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3655 \begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3656 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
3657 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
3658 \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
3659 exception if unsuccessful.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3660 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
3661 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3662
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3663 \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3664 int low, int high,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3665 PyObject *itemlist}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3666 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
3667 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
3668 \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
3669 \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
3670 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3671
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3672 \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
3673 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
3674 \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
3675 \samp{\var{list}.sort()}.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3676 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3677
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3678 \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
3679 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
3680 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
3681 \samp{\var{list}.reverse()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3682 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3683
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3684 \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
3685 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
3686 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
3687 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3688
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3689
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3690 \section{Mapping Objects \label{mapObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3691
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3692 \obindex{mapping}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3693
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3694
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3695 \subsection{Dictionary Objects \label{dictObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3696
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3697 \obindex{dictionary}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3698 \begin{ctypedesc}{PyDictObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3699 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
3700 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3701
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3702 \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
3703 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
3704 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
3705 \code{types.DictionaryType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3706 \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
3707 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3708
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3709 \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
3710 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
3711 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3712
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3713 \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
3714 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
3715 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3716
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3717 \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
3718 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
3719 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3720
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
3721 \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
3722 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
3723 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
3724 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3725
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3726 \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
3727 PyObject *val}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3728 Inserts \var{value} into the dictionary \var{p} with a key of \var{key}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3729 \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
3730 raised.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3731 Returns \code{0} on success or \code{-1} on failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3732 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3733
17057
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3734 \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3735 char *key,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3736 PyObject *val}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3737 Inserts \var{value} into the dictionary \var{p} using \var{key}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3738 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
3739 created using \code{PyString_FromString(\var{key})}.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3740 Returns \code{0} on success or \code{-1} on failure.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3741 \ttindex{PyString_FromString()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3742 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3743
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3744 \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
3745 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
3746 \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
3747 raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3748 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3749
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3750 \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
3751 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
3752 specified by the string \var{key}.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3753 Returns \code{0} on success or \code{-1} on failure.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3754 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3755
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3756 \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
3757 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
3758 \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
3759 \emph{without} setting an exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3760 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3761
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3762 \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
3763 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
3764 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
3765 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3766
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3767 \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
3768 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
3769 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
3770 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
3771 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3772
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3773 \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
3774 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
3775 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
3776 \citetitle[../lib/lib.html]{Python Library Reference}).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3777 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3778
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3779 \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
3780 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
3781 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
3782 \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
3783 Reference}).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3784 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3785
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3786 \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
3787 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
3788 \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
3789 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3790
17057
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3791 \begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos,
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
3792 PyObject **pkey, PyObject **pvalue}
17057
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3793 Iterate over all key-value pairs in the dictionary \var{p}. The
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3794 \ctype{int} referred to by \var{ppos} must be initialized to \code{0}
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3795 prior to the first call to this function to start the iteration; the
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3796 function returns true for each pair in the dictionary, and false once
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3797 all pairs have been reported. The parameters \var{pkey} and
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3798 \var{pvalue} should either point to \ctype{PyObject*} variables that
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3799 will be filled in with each key and value, respectively, or may be
17504
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3800 \NULL.
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3801
17057
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3802 For example:
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3803
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3804 \begin{verbatim}
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3805 PyObject *key, *value;
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3806 int pos = 0;
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3807
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3808 while (PyDict_Next(self->dict, &pos, &key, &value)) {
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3809 /* do something interesting with the values... */
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3810 ...
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3811 }
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3812 \end{verbatim}
17504
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3813
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3814 The dictionary \var{p} should not be mutated during iteration. It is
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3815 safe (since Python 2.1) to modify the values of the keys as you
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3816 iterate over the dictionary, for example:
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3817
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3818 \begin{verbatim}
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3819 PyObject *key, *value;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3820 int pos = 0;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3821
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3822 while (PyDict_Next(self->dict, &pos, &key, &value)) {
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3823 int i = PyInt_AS_LONG(value) + 1;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3824 PyObject *o = PyInt_FromLong(i);
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3825 if (o == NULL)
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3826 return -1;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3827 if (PyDict_SetItem(self->dict, key, o) < 0) {
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3828 Py_DECREF(o);
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3829 return -1;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3830 }
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3831 Py_DECREF(o);
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3832 }
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
3833 \end{verbatim}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3834 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3835
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3836
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3837 \section{Other Objects \label{otherObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3838
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3839 \subsection{File Objects \label{fileObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3840
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3841 \obindex{file}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3842 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
3843 \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
3844 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
3845
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3846 \begin{ctypedesc}{PyFileObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3847 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
3848 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3849
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3850 \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
3851 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
3852 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
3853 \withsubitem{(in module types)}{\ttindex{FileType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3854 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3855
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3856 \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
3857 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
3858 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3859
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3860 \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
3861 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
3862 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
3863 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
3864 \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
3865 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3866
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3867 \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
3868 char *name, char *mode,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3869 int (*close)(FILE*)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3870 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
3871 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
3872 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
3873 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3874
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3875 \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
3876 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
3877 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3878
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3879 \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
3880 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
3881 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
3882 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
3883 \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
3884 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
3885 \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
3886 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
3887 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
3888 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
3889 \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
3890 immediately.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3891 \withsubitem{(built-in exception)}{\ttindex{EOFError}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3892 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3893
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3894 \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
3895 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
3896 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3897
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3898 \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
3899 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
3900 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
3901 creation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3902 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3903
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3904 \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
3905 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
3906 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
3907 \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
3908 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
3909 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
3910 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
3911 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
3912 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
3913 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
3914 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
3915 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3916
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3917 \begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3918 int flags}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3919 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
3920 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
3921 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
3922 \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
3923 failure; the appropriate exception will be set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3924 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3925
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3926 \begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3927 int flags}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3928 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
3929 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
3930 set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3931 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3932
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3933
16318
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3934 \subsection{Instance Objects \label{instanceObjects}}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3935
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3936 \obindex{instance}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3937 There are very few functions specific to instance objects.
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3938
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3939 \begin{cvardesc}{PyTypeObject}{PyInstance_Type}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3940 Type object for class instances.
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3941 \end{cvardesc}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3942
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3943 \begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3944 Returns true if \var{obj} is an instance.
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3945 \end{cfuncdesc}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3946
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3947 \begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class,
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3948 PyObject *arg,
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3949 PyObject *kw}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3950 Create a new instance of a specific class. The parameters \var{arg}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3951 and \var{kw} are used as the positional and keyword parameters to
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3952 the object's constructor.
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3953 \end{cfuncdesc}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3954
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3955 \begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class,
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3956 PyObject *dict}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3957 Create a new instance of a specific class without calling it's
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3958 constructor. \var{class} is the class of new object. The
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3959 \var{dict} parameter will be used as the object's \member{__dict__};
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3960 if \NULL, a new dictionary will be created for the instance.
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3961 \end{cfuncdesc}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3962
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
3963
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3964 \subsection{Module Objects \label{moduleObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3965
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3966 \obindex{module}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3967 There are only a few functions special to module objects.
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3968
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3969 \begin{cvardesc}{PyTypeObject}{PyModule_Type}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3970 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
3971 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
3972 \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
3973 \end{cvardesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3974
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3975 \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
3976 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
3977 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3978
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3979 \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
3980 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
3981 \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
3982 \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
3983 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
3984 \withsubitem{(module attribute)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3985 \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
3986 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3987
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3988 \begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3989 Return the dictionary object that implements \var{module}'s namespace;
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3990 this object is the same as the \member{__dict__} attribute of the
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3991 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
3992 \withsubitem{(module attribute)}{\ttindex{__dict__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3993 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3994
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3995 \begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3996 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
3997 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
3998 raised and \NULL{} is returned.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3999 \withsubitem{(module attribute)}{\ttindex{__name__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4000 \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
4001 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4002
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4003 \begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4004 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
4005 \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
4006 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
4007 \NULL.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4008 \withsubitem{(module attribute)}{\ttindex{__file__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4009 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4010 \end{cfuncdesc}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4011
14782
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4012 \begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module,
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4013 char *name, PyObject *value}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4014 Add an object to \var{module} as \var{name}. This is a convenience
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4015 function which can be used from the module's initialization function.
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4016 This steals a reference to \var{value}. Returns \code{-1} on error,
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4017 \code{0} on success.
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4018 \versionadded{2.0}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4019 \end{cfuncdesc}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4020
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4021 \begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module,
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4022 char *name, int value}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4023 Add an integer constant to \var{module} as \var{name}. This convenience
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4024 function can be used from the module's initialization function.
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4025 Returns \code{-1} on error, \code{0} on success.
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4026 \versionadded{2.0}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4027 \end{cfuncdesc}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4028
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4029 \begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module,
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4030 char *name, char *value}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4031 Add a string constant to \var{module} as \var{name}. This convenience
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4032 function can be used from the module's initialization function. The
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4033 string \var{value} must be null-terminated. Returns \code{-1} on
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4034 error, \code{0} on success.
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4035 \versionadded{2.0}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4036 \end{cfuncdesc}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4037
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4038
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4039 \subsection{CObjects \label{cObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4040
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4041 \obindex{CObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4042 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
4043 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
4044 information on using these objects.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4045
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4046
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
4047 \begin{ctypedesc}{PyCObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
4048 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
4049 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
4050 \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
4051 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
4052 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
4053 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
4054 \end{ctypedesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
4055
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4056 \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
4057 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
4058 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4059
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4060 \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj,
15953
8349b4dfc51a Undoing the whitespace patches which sneaked into the earlier patch.
Marc-André Lemburg <mal@egenix.com>
parents: 15952
diff changeset
4061 void (*destr)(void *)}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
4062 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
4063 \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
4064 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
4065 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
4066
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4067 \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj,
15953
8349b4dfc51a Undoing the whitespace patches which sneaked into the earlier patch.
Marc-André Lemburg <mal@egenix.com>
parents: 15952
diff changeset
4068 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
4069 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
4070 \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
4071 \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
4072 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
4073 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
4074
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4075 \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
4076 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
4077 \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
4078 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4079
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4080 \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
4081 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
4082 \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
4083 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4084
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4085
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4086 \chapter{Initialization, Finalization, and Threads
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4087 \label{initialization}}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4088
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4089 \begin{cfuncdesc}{void}{Py_Initialize}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4090 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
4091 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
4092 functions; with the exception of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4093 \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
4094 \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
4095 \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
4096 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
4097 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
4098 \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
4099 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
4100 \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
4101 \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
4102 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
4103 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
4104 \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
4105 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
4106 \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
4107 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
4108 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
4109
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
4110 \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
4111 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
4112 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
4113 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
4114 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4115 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4116
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4117 \begin{cfuncdesc}{void}{Py_Finalize}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4118 Undo all initializations made by \cfunction{Py_Initialize()} and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4119 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
4120 sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4121 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
4122 \cfunction{Py_Initialize()}. Ideally, this frees all memory allocated
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4123 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
4124 time (without calling \cfunction{Py_Initialize()} again first). There
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4125 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
4126
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4127 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
4128 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
4129 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
4130 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
4131 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
4132 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
4133 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
4134
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4135 \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
4136 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
4137 (\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
4138 (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
4139 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
4140 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
4141 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
4142 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
4143 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
4144 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
4145 calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4146 than once.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4147 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4148
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4149 \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
4150 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
4151 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
4152 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
4153 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
4154 \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
4155 \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
4156 \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
4157 (\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
4158 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
4159 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
4160 \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
4161 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
4162 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4163 \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
4164
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4165 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
4166 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
4167 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
4168 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
4169 \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
4170 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
4171 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
4172 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
4173 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
4174 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
4175
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4176 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
4177 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
4178 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
4179 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
4180 (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
4181 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
4182 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
4183 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
4184 re-initialized by calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4185 \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
4186 \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
4187 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
4188 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4189
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4190 \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
4191 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
4192 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
4193 \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
4194 \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
4195 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
4196 (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
4197 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
4198 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
4199 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
4200 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
4201 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
4202 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
4203 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
4204 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
4205 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
4206 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4207
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4208 \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
4209 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
4210 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
4211 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
4212 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
4213 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
4214 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
4215 \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
4216 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
4217 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4218
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4219 \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
4220 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
4221 \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
4222 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
4223 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
4224 \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
4225 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
4226 functions below to find the Python run-time libraries relative to the
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4227 interpreter executable. The default value is \code{'python'}. The
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4228 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
4229 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
4230 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
4231 the contents of this storage.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4232 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4233
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4234 \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
4235 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
4236 \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
4237 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
4238 should not modify its value.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4239 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4240
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4241 \begin{cfuncdesc}{char*}{Py_GetPrefix}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4242 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
4243 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
4244 set with \cfunction{Py_SetProgramName()} and some environment variables;
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4245 for example, if the program name is \code{'/usr/local/bin/python'},
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4246 the prefix is \code{'/usr/local'}. The returned string points into
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4247 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
4248 corresponds to the \makevar{prefix} variable in the top-level
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4249 \file{Makefile} and the \longprogramopt{prefix} argument to the
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4250 \program{configure} script at build time. The value is available to
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
4251 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
4252 also the next function.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4253 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4254
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4255 \begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4256 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
4257 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
4258 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
4259 variables; for example, if the program name is
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4260 \code{'/usr/local/bin/python'}, the exec-prefix is
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4261 \code{'/usr/local'}. The returned string points into static storage;
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4262 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
4263 \makevar{exec_prefix} variable in the top-level \file{Makefile} and the
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4264 \longprogramopt{exec-prefix} argument to the
11453
a05a05602902 Missed a couple of program options that had been marked by \code.
Fred Drake <fdrake@acm.org>
parents: 11451
diff changeset
4265 \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
4266 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
4267
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4268 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
4269 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
4270 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
4271 platform dependent files may be installed in the
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4272 \file{/usr/local/plat} subtree while platform independent may be
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4273 installed in \file{/usr/local}.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4274
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4275 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
4276 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
4277 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
4278 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
4279 Linux are yet another platform. Different major revisions of the same
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
4280 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
4281 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
4282 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
4283 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
4284 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
4285 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
4286
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4287 System administrators will know how to configure the \program{mount} or
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4288 \program{automount} programs to share \file{/usr/local} between platforms
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4289 while having \file{/usr/local/plat} be a different filesystem for each
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4290 platform.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4291 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4292
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4293 \begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4294 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
4295 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
4296 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
4297 \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
4298 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
4299 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
4300 \code{sys.executable}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4301 \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
4302 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4303
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4304 \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
4305 \indexiii{module}{search}{path}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4306 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
4307 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
4308 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
4309 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
4310 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
4311 DOS/Windows, and \character{\e n} (the \ASCII{} newline character) on
7271
0061d3916ae4 "ASCII" --> "\ASCII{}"
Fred Drake <fdrake@acm.org>
parents: 7269
diff changeset
4312 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
4313 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
4314 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
4315 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
4316 modules.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4317
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4318 % XXX should give the exact rules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4319 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4320
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4321 \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
4322 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
4323 looks something like
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4324
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
4325 \begin{verbatim}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4326 "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
4327 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4328
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4329 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
4330 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
4331 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
4332 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
4333 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
4334 \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
4335 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4336
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4337 \begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
4338 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
4339 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
4340 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
4341 for Solaris 2.x, which is also known as SunOS 5.x, the value is
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4342 \code{'sunos5'}. On Macintosh, it is \code{'mac'}. On Windows, it
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4343 is \code{'win'}. The returned string points into static storage;
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4344 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
4345 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
4346 \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
4347 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4348
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4349 \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
4350 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
4351 for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4352
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4353 \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4354
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4355 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
4356 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
4357 \code{sys.copyright}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4358 \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
4359 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4360
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4361 \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
4362 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
4363 version, in square brackets, for example:
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4364
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4365 \begin{verbatim}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4366 "[GCC 2.7.2.2]"
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4367 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4368
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4369 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
4370 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
4371 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
4372 \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
4373 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4374
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4375 \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
4376 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
4377 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
4378
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
4379 \begin{verbatim}
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
4380 "#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
4381 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4382
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4383 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
4384 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
4385 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
4386 \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
4387 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4388
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4389 \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
4390 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
4391 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
4392 \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
4393 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
4394 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
4395 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
4396 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
4397 condition is signalled using
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4398 \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
4399 \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
4400 % 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
4401 % check w/ Guido.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4402 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4403
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4404 % 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
4405
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4406 \section{Thread State and the Global Interpreter Lock
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4407 \label{threads}}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4408
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4409 \index{global interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4410 \index{interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4411 \index{lock, interpreter}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4412
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4413 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
4414 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
4415 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
4416 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
4417 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
4418 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
4419 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
4420
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4421 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
4422 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
4423 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
4424 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
4425 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
4426 \withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4427 \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
4428 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
4429 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
4430 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
4431
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4432 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
4433 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
4434 \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
4435 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
4436 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
4437 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
4438 \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
4439 \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
4440 current thread.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4441
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4442 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
4443 \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
4444 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
4445 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
4446 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
4447 manipulated explicitly.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4448
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4449 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
4450 interpreter lock has the following simple structure:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4451
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4452 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4453 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
4454 Release the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4455 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4456 Reacquire the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4457 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
4458 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4459
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4460 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
4461
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4462 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4463 Py_BEGIN_ALLOW_THREADS
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4464 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4465 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
4466 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4467
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4468 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
4469 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
4470 \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
4471 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
4472 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
4473 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
4474
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4475 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
4476 following code:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4477
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4478 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4479 PyThreadState *_save;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4480
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4481 _save = PyEval_SaveThread();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4482 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4483 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
4484 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4485
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4486 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
4487 as follows:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4488
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4489 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4490 PyThreadState *_save;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4491
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4492 _save = PyThreadState_Swap(NULL);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4493 PyEval_ReleaseLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4494 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4495 PyEval_AcquireLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4496 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
4497 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4498
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4499 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
4500 \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
4501 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
4502 \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
4503 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
4504 is disabled,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4505 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4506 \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
4507 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
4508 \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
4509 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
4510 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
4511 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
4512
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4513 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
4514 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
4515 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
4516 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
4517 lock and store its own thread state in the global variable).
14926
76c1e40c5c5d Reversely --> Conversely
Fred Drake <fdrake@acm.org>
parents: 14870
diff changeset
4518 Conversely, when acquiring the lock and restoring the thread state,
76c1e40c5c5d Reversely --> Conversely
Fred Drake <fdrake@acm.org>
parents: 14870
diff changeset
4519 the lock must be acquired before storing the thread state pointer.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4520
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4521 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
4522 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
4523 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
4524 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
4525 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
4526 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
4527 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
4528 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
4529 structure.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4530
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4531 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
4532 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
4533 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
4534 interpreter, for example the module administration
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4535 (\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
4536 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
4537 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
4538 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
4539 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
4540 thread after Python is initialized).
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4541
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4542
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4543 \begin{ctypedesc}{PyInterpreterState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4544 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
4545 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
4546 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
4547 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
4548
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4549 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
4550 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
4551 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
4552 regardless of to which interpreter they belong.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4553 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4554
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4555 \begin{ctypedesc}{PyThreadState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4556 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
4557 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
4558 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
4559 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4560
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4561 \begin{cfuncdesc}{void}{PyEval_InitThreads}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4562 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
4563 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
4564 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
4565 \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
4566 \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
4567 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
4568 \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
4569 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4570
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4571 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
4572 this function before calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4573 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4574
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4575 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
4576 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
4577 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
4578 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
4579 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
4580 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
4581 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
4582 \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
4583 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
4584 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
4585 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
4586 has acquired it.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4587
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4588 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
4589 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
4590
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4591 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
4592 compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4593 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4594
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4595 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4596 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
4597 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
4598 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
4599 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4600 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4601
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4602 \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4603 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
4604 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
4605 disabled at compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4606 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4607
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4608 \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
4609 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
4610 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
4611 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
4612 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
4613 is disabled at compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4614 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4615
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4616 \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
4617 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
4618 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
4619 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
4620 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
4621 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
4622 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
4623 time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4624 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4625
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4626 \begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4627 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
4628 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
4629 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
4630 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
4631 (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
4632 compile time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4633 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4634
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4635 \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4636 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
4637 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
4638 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
4639 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
4640 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
4641 time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4642 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4643
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4644 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
4645 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
4646
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4647 \begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4648 This macro expands to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4649 \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4650 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
4651 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
4652 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
4653 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4654 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4655
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4656 \begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4657 This macro expands to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4658 \samp{PyEval_RestoreThread(_save); \}}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4659 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
4660 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
4661 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
4662 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4663 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4664
18438
05c49346b68b Fix for SF bug #436525, reported by Greg Kochanski:
Thomas Wouters <thomas@python.org>
parents: 18192
diff changeset
4665 \begin{csimplemacrodesc}{Py_BLOCK_THREADS}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4666 This macro expands to \samp{PyEval_RestoreThread(_save);}: it
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4667 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
4668 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
4669 time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4670 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4671
18438
05c49346b68b Fix for SF bug #436525, reported by Greg Kochanski:
Thomas Wouters <thomas@python.org>
parents: 18192
diff changeset
4672 \begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4673 This macro expands to \samp{_save = PyEval_SaveThread();}: it is
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4674 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
4675 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
4676 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4677 \end{csimplemacrodesc}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4678
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4679 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
4680 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
4681 interpreter lock has been created.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4682
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4683 \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
4684 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
4685 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
4686 function.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4687 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4688
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4689 \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4690 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
4691 lock must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4692 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4693
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4694 \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4695 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
4696 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
4697 call to \cfunction{PyInterpreterState_Clear()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4698 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4699
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4700 \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
4701 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
4702 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
4703 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
4704 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4705
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4706 \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4707 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
4708 must be held.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4709 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4710
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4711 \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4712 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
4713 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
4714 call to \cfunction{PyThreadState_Clear()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4715 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4716
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4717 \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4718 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
4719 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
4720 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
4721 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4722
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4723 \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
4724 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
4725 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
4726 must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4727 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4728
17877
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
4729 \begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
4730 Return a dictionary in which extensions can store thread-specific
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
4731 state information. Each extension should use a unique key to use to
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
4732 store state in the dictionary. If this function returns \NULL, an
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
4733 exception has been raised and the caller should allow it to
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
4734 propogate.
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
4735 \end{cfuncdesc}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
4736
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4737
18671
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4738 \section{Profiling and Tracing \label{profiling}}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4739
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4740 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4741
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4742 The Python interpreter provides some low-level support for attaching
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4743 profiling and execution tracing facilities. These are used for
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4744 profiling, debugging, and coverage analysis tools.
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4745
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4746 Starting with Python 2.2, the implementation of this facility was
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4747 substantially revised, and an interface from C was added. This C
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4748 interface allows the profiling or tracing code to avoid the overhead
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4749 of calling through Python-level callable objects, making a direct C
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4750 function call instead. The essential attributes of the facility have
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4751 not changed; the interface allows trace functions to be installed
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4752 per-thread, and the basic events reported to the trace function are
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4753 the same as had been reported to the Python-level trace functions in
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4754 previous versions.
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4755
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4756 \begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj,
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4757 PyFrameObject *frame, int what,
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4758 PyObject *arg)}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4759 The type of the trace function registered using
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4760 \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}.
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4761 The first parameter is the object passed to the registration
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4762 function,
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4763 \end{ctypedesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4764
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4765 \begin{cvardesc}{int}{PyTrace_CALL}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4766 The value of the \var{what} parameter to a \ctype{Py_tracefunc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4767 function when a new function or method call is being reported.
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4768 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4769
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4770 \begin{cvardesc}{int}{PyTrace_EXCEPT}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4771 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4772
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4773 \begin{cvardesc}{int}{PyTrace_LINE}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4774 The value passed as the \var{what} parameter to a trace function
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4775 (but not a profiling function) when a line-number event is being
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4776 reported.
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4777 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4778
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4779 \begin{cvardesc}{int}{PyTrace_RETURN}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4780 The value for the \var{what} parameter to \ctype{Py_tracefunc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4781 functions when a call is returning without propogating an exception.
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4782 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4783
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4784 \begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4785 \end{cfuncdesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4786
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4787 \begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4788 \end{cfuncdesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4789
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
4790
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4791 \chapter{Memory Management \label{memory}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4792 \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
4793
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4794
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4795 \section{Overview \label{memoryOverview}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4796
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4797 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
4798 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
4799 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
4800 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
4801 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
4802 preallocation or caching.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4803
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4804 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
4805 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
4806 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
4807 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
4808 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
4809 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
4810 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
4811 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
4812 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
4813 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
4814 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
4815 the private heap.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4816
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4817 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
4818 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
4819 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
4820 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
4821 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
4822 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
4823 this document.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4824
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4825 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
4826 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
4827 library: \cfunction{malloc()}\ttindex{malloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4828 \cfunction{calloc()}\ttindex{calloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4829 \cfunction{realloc()}\ttindex{realloc()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4830 \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
4831 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
4832 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
4833 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
4834 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
4835 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
4836
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4837 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4838 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4839 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
4840
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4841 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4842 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4843 ...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
4844 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4845 free(buf); /* malloc'ed */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4846 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4847 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4848
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4849 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
4850 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
4851 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
4852
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4853 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
4854 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
4855 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
4856 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
4857 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
4858 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
4859 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
4860 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
4861 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
4862 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
4863 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
4864 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
4865 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
4866 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
4867 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
4868
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4869
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4870 \section{Memory Interface \label{memoryInterface}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4871
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4872 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
4873 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
4874
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4875
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4876 \begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n}
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4877 Allocates \var{n} bytes and returns a pointer of type \ctype{void*} to
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4878 the allocated memory, or \NULL{} if the request fails. Requesting zero
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4879 bytes returns a non-\NULL{} pointer.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4880 The memory will not have been initialized in any way.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4881 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4882
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4883 \begin{cfuncdesc}{void*}{PyMem_Realloc}{void *p, size_t n}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4884 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
4885 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
4886 sizes. If \var{p} is \NULL{}, the call is equivalent to
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4887 \cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4888 memory block is resized but is not freed, and the returned pointer is
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4889 non-\NULL{}. Unless \var{p} is \NULL{}, it must have been returned by
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4890 a previous call to \cfunction{PyMem_Malloc()} or
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4891 \cfunction{PyMem_Realloc()}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4892 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4893
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
4894 \begin{cfuncdesc}{void}{PyMem_Free}{void *p}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4895 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
4896 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
4897 \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
4898 \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
4899 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
4900 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4901
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4902 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
4903 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
4904
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4905 \begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4906 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
4907 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
4908 \ctype{\var{TYPE}*}.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4909 The memory will not have been initialized in any way.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4910 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4911
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4912 \begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4913 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
4914 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
4915 cast to \ctype{\var{TYPE}*}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4916 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4917
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4918 \begin{cfuncdesc}{void}{PyMem_Del}{void *p}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4919 Same as \cfunction{PyMem_Free()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4920 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4921
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4922 In addition, the following macro sets are provided for calling the
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4923 Python memory allocator directly, without involving the C API functions
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4924 listed above. However, note that their use does not preserve binary
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4925 compatibility accross Python versions and is therefore deprecated in
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4926 extension modules.
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4927
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4928 \cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}.
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4929
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4930 \cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}.
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4931
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4932
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4933 \section{Examples \label{memoryExamples}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4934
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4935 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
4936 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
4937 first function set:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4938
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4939 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4940 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4941 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
4942
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4943 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4944 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4945 /* ...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
4946 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4947 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
4948 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4949 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4950
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4951 The same code using the type-oriented function set:
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4952
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4953 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4954 PyObject *res;
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4955 char *buf = PyMem_New(char, BUFSIZ); /* for I/O */
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4956
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4957 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4958 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4959 /* ...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
4960 res = PyString_FromString(buf);
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4961 PyMem_Del(buf); /* allocated with PyMem_New */
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4962 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4963 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4964
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4965 Note that in the two examples above, the buffer is always
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4966 manipulated via functions belonging to the same set. Indeed, it
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4967 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
4968 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
4969 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
4970 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
4971 allocators operating on different heaps.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4972
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4973 \begin{verbatim}
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4974 char *buf1 = PyMem_New(char, BUFSIZ);
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4975 char *buf2 = (char *) malloc(BUFSIZ);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4976 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
4977 ...
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4978 PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4979 free(buf2); /* Right -- allocated via malloc() */
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4980 free(buf1); /* Fatal -- should be PyMem_Del() */
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4981 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4982
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4983 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
4984 the Python heap, objects in Python are allocated and released with
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4985 \cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4986 \cfunction{PyObject_Del()}, or with their corresponding macros
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
4987 \cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and
13217
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 13150
diff changeset
4988 \cfunction{PyObject_DEL()}.
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 13150
diff changeset
4989
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 13150
diff changeset
4990 These will be explained in the next chapter on defining and
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 13150
diff changeset
4991 implementing new object types in C.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4992
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4993
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4994 \chapter{Defining New Object Types \label{newTypes}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4995
18785
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
4996
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
4997 \section{Allocating Objects on the Heap
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
4998 \label{allocating-objects}}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
4999
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
5000 \begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
5001 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
5002
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5003 \begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5004 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5005
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5006 \begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5007 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5008
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5009 \begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op,
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5010 PyTypeObject *type}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5011 Initialize a newly-allocated object \var{op} with its type and
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5012 initial reference. Returns the initialized object. If \var{type}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5013 indicates that the object participates in the cyclic garbage
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5014 detector, it it added to the detector's set of observed objects.
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5015 Other fields of the object are not affected.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5016 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5017
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5018 \begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op,
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5019 PyTypeObject *type, int size}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5020 This does everything \cfunction{PyObject_Init()} does, and also
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5021 initializes the length information for a variable-size object.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5022 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5023
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5024 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5025 Allocate a new Python object using the C structure type \var{TYPE}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5026 and the Python type object \var{type}. Fields not defined by the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5027 Python object header are not initialized; the object's reference
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5028 count will be one. The size of the memory
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5029 allocation is determined from the \member{tp_basicsize} field of the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5030 type object.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5031 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5032
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5033 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type,
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5034 int size}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5035 Allocate a new Python object using the C structure type \var{TYPE}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5036 and the Python type object \var{type}. Fields not defined by the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5037 Python object header are not initialized. The allocated memory
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5038 allows for the \var{TYPE} structure plus \var{size} fields of the
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5039 size given by the \member{tp_itemsize} field of \var{type}. This is
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5040 useful for implementing objects like tuples, which are able to
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5041 determine their size at construction time. Embedding the array of
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5042 fields into the same allocation decreases the number of allocations,
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5043 improving the memory management efficiency.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5044 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5045
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5046 \begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5047 Releases memory allocated to an object using
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5048 \cfunction{PyObject_New()} or \cfunction{PyObject_NewVar()}. This
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5049 is normally called from the \member{tp_dealloc} handler specified in
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5050 the object's type. The fields of the object should not be accessed
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5051 after this call as the memory is no longer a valid Python object.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5052 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5053
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5054 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW}{TYPE, PyTypeObject *type}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5055 Macro version of \cfunction{PyObject_New()}, to gain performance at
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5056 the expense of safety. This does not check \var{type} for a \NULL{}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5057 value.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5058 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5059
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5060 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type,
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5061 int size}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5062 Macro version of \cfunction{PyObject_NewVar()}, to gain performance
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5063 at the expense of safety. This does not check \var{type} for a
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5064 \NULL{} value.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5065 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5066
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5067 \begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5068 Macro version of \cfunction{PyObject_Del()}.
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
5069 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
5070
15444
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5071 \begin{cfuncdesc}{PyObject*}{Py_InitModule}{char *name,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5072 PyMethodDef *methods}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5073 Create a new module object based on a name and table of functions,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5074 returning the new module object.
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5075 \end{cfuncdesc}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5076
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5077 \begin{cfuncdesc}{PyObject*}{Py_InitModule3}{char *name,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5078 PyMethodDef *methods,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5079 char *doc}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5080 Create a new module object based on a name and table of functions,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5081 returning the new module object. If \var{doc} is non-\NULL, it will
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5082 be used to define the docstring for the module.
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5083 \end{cfuncdesc}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5084
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5085 \begin{cfuncdesc}{PyObject*}{Py_InitModule4}{char *name,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5086 PyMethodDef *methods,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5087 char *doc, PyObject *self,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5088 int apiver}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5089 Create a new module object based on a name and table of functions,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5090 returning the new module object. If \var{doc} is non-\NULL, it will
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5091 be used to define the docstring for the module. If \var{self} is
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5092 non-\NULL, it will passed to the functions of the module as their
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5093 (otherwise \NULL) first parameter. (This was added as an
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5094 experimental feature, and there are no known uses in the current
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5095 version of Python.) For \var{apiver}, the only value which should
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5096 be passed is defined by the constant \constant{PYTHON_API_VERSION}.
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5097
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5098 \strong{Note:} Most uses of this function should probably be using
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5099 the \cfunction{Py_InitModule3()} instead; only use this if you are
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5100 sure you need it.
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5101 \end{cfuncdesc}
8057
5aacdd097941 Some patches by Drew Csillag; plus a few of my own uncommitted changes.
Guido van Rossum <guido@python.org>
parents: 8029
diff changeset
5102
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5103 DL_IMPORT
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5104
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5105 \begin{cvardesc}{PyObject}{_Py_NoneStruct}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5106 Object which is visible in Python as \code{None}. This should only
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5107 be accessed using the \code{Py_None} macro, which evaluates to a
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5108 pointer to this object.
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5109 \end{cvardesc}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5110
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5111
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5112 \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
5113
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5114 PyObject, PyVarObject
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5115
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5116 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
5117
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5118 Typedefs:
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5119 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
5120 intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5121 destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5122 setattrofunc, cmpfunc, reprfunc, hashfunc
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5123
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5124 \begin{ctypedesc}{PyCFunction}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5125 Type of the functions used to implement most Python callables in C.
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5126 \end{ctypedesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5127
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5128 \begin{ctypedesc}{PyMethodDef}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5129 Structure used to describe a method of an extension type. This
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5130 structure has four fields:
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5131
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5132 \begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5133 \lineiii{ml_name}{char *}{name of the method}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5134 \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5135 \lineiii{ml_flags}{int}{flag bits indicating how the call should be
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5136 constructed}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5137 \lineiii{ml_doc}{char *}{points to the contents of the docstring}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5138 \end{tableiii}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5139 \end{ctypedesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5140
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5141 \begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef[] table,
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5142 PyObject *ob, char *name}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5143 Return a bound method object for an extension type implemented in C.
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5144 This function also handles the special attribute \member{__methods__},
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5145 returning a list of all the method names defined in \var{table}.
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5146 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5147
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5148
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5149 \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
5150
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5151 \begin{ctypedesc}{PyMappingMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5152 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
5153 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
5154 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5155
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5156
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5157 \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
5158
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5159 \begin{ctypedesc}{PyNumberMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5160 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
5161 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
5162 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5163
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5164
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5165 \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
5166
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5167 \begin{ctypedesc}{PySequenceMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5168 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
5169 to implement the sequence protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5170 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5171
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5172
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5173 \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
5174 \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
5175
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5176 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
5177 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
5178 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
5179 \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
5180
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5181 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
5182 \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
5183 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
5184 a \ctype{PyBufferProcs} structure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5185
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5186 \strong{Note:} It is very important that your
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5187 \ctype{PyTypeObject} structure uses \constant{Py_TPFLAGS_DEFAULT} for
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5188 the value of the \member{tp_flags} member rather than \code{0}. This
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5189 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
5190 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
5191 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
5192 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
5193
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5194 \begin{ctypedesc}{PyBufferProcs}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5195 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
5196 implementation of the buffer protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5197
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5198 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
5199 \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
5200 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
5201 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
5202 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
5203
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5204 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
5205 \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
5206 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
5207
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5208 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
5209 \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
5210 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
5211 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
5212 \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
5213
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5214 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
5215 \ctype{getcharbufferproc}. This slot will only be present if the
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5216 \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5217 \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
5218 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
5219 \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
5220 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
5221 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
5222 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
5223 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
5224 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
5225 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
5226 \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
5227 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
5228 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
5229 have character-based content.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5230
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5231 \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
5232 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
5233 \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
5234 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5235
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5236 \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
5237 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
5238 \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
5239 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
5240 \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
5241 \end{datadesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5242
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5243 \begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5244 (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
5245 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
5246 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
5247 \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
5248 positive, and strictly less than the number of segments returned by
17336
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents: 17307
diff changeset
5249 the \member{bf_getsegcount} slot function. On success, it returns the
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents: 17307
diff changeset
5250 length of the buffer memory, and sets \code{*\var{ptrptr}} to a
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents: 17307
diff changeset
5251 pointer to that memory.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5252 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5253
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5254 \begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5255 (PyObject *self, int segment, void **ptrptr)}
17336
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents: 17307
diff changeset
5256 Return a pointer to a writable memory buffer in \code{*\var{ptrptr}},
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents: 17307
diff changeset
5257 and the length of that segment as the function return value.
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents: 17307
diff changeset
5258 The memory buffer must correspond to buffer segment \var{segment}.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
5259 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
5260 \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
5261 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
5262 \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
5263 % 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
5264 % 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
5265 % 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
5266 % code.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
5267 \end{ctypedesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
5268
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5269 \begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5270 (PyObject *self, int *lenp)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5271 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
5272 \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
5273 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
5274 The function cannot fail.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5275 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5276
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5277 \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5278 (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
5279 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5280
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5281
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5282 \section{Supporting Cyclic Garbarge Collection
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5283 \label{supporting-cycle-detection}}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5284
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5285 Python's support for detecting and collecting garbage which involves
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5286 circular references requires support from object types which are
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5287 ``containers'' for other objects which may also be containers. Types
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5288 which do not store references to other objects, or which only store
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5289 references to atomic types (such as numbers or strings), do not need
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5290 to provide any explicit support for garbage collection.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5291
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5292 To create a container type, the \member{tp_flags} field of the type
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5293 object must include the \constant{Py_TPFLAGS_GC} and provide an
17147
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5294 implementation of the \member{tp_traverse} handler. The computed
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5295 value of the \member{tp_basicsize} field must include
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5296 \constant{PyGC_HEAD_SIZE} as well. If instances of the type are
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5297 mutable, a \member{tp_clear} implementation must also be provided.
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5298
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5299 \begin{datadesc}{Py_TPFLAGS_GC}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5300 Objects with a type with this flag set must conform with the rules
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5301 documented here. For convenience these objects will be referred to
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5302 as container objects.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5303 \end{datadesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5304
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5305 \begin{datadesc}{PyGC_HEAD_SIZE}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5306 Extra memory needed for the garbage collector. Container objects
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5307 must include this in the calculation of their tp_basicsize. If the
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5308 collector is disabled at compile time then this is \code{0}.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5309 \end{datadesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5310
17147
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5311 Constructors for container types must conform to two rules:
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5312
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5313 \begin{enumerate}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5314 \item The memory for the object must be allocated using
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5315 \cfunction{PyObject_New()} or \cfunction{PyObject_VarNew()}.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5316
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5317 \item Once all the fields which may contain references to other
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5318 containers are initialized, it must call
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5319 \cfunction{PyObject_GC_Init()}.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5320 \end{enumerate}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5321
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5322 \begin{cfuncdesc}{void}{PyObject_GC_Init}{PyObject *op}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5323 Adds the object \var{op} to the set of container objects tracked by
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5324 the collector. The collector can run at unexpected times so objects
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5325 must be valid while being tracked. This should be called once all
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5326 the fields followed by the \member{tp_traverse} handler become valid,
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5327 usually near the end of the constructor.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5328 \end{cfuncdesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5329
17147
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5330 Similarly, the deallocator for the object must conform to a similar
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5331 pair of rules:
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5332
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5333 \begin{enumerate}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5334 \item Before fields which refer to other containers are invalidated,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5335 \cfunction{PyObject_GC_Fini()} must be called.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5336
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5337 \item The object's memory must be deallocated using
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5338 \cfunction{PyObject_Del()}.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5339 \end{enumerate}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5340
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5341 \begin{cfuncdesc}{void}{PyObject_GC_Fini}{PyObject *op}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5342 Remove the object \var{op} from the set of container objects tracked
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5343 by the collector. Note that \cfunction{PyObject_GC_Init()} can be
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5344 called again on this object to add it back to the set of tracked
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5345 objects. The deallocator (\member{tp_dealloc} handler) should call
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5346 this for the object before any of the fields used by the
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5347 \member{tp_traverse} handler become invalid.
17209
52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini().
Fred Drake <fdrake@acm.org>
parents: 17147
diff changeset
5348
52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini().
Fred Drake <fdrake@acm.org>
parents: 17147
diff changeset
5349 \strong{Note:} Any container which may be referenced from another
52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini().
Fred Drake <fdrake@acm.org>
parents: 17147
diff changeset
5350 object reachable by the collector must itself be tracked by the
52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini().
Fred Drake <fdrake@acm.org>
parents: 17147
diff changeset
5351 collector, so it is generally not safe to call this function
52da094b53ec Strengthen the constraints on calling PyObject_GC_Fini().
Fred Drake <fdrake@acm.org>
parents: 17147
diff changeset
5352 anywhere but in the object's deallocator.
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5353 \end{cfuncdesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5354
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5355 The \member{tp_traverse} handler accepts a function parameter of this
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5356 type:
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5357
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5358 \begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5359 Type of the visitor function passed to the \member{tp_traverse}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5360 handler. The function should be called with an object to traverse
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5361 as \var{object} and the third parameter to the \member{tp_traverse}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5362 handler as \var{arg}.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5363 \end{ctypedesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5364
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5365 The \member{tp_traverse} handler must have the following type:
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5366
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5367 \begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self,
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5368 visitproc visit, void *arg)}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5369 Traversal function for a container object. Implementations must
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5370 call the \var{visit} function for each object directly contained by
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5371 \var{self}, with the parameters to \var{visit} being the contained
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5372 object and the \var{arg} value passed to the handler. If
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5373 \var{visit} returns a non-zero value then an error has occurred and
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5374 that value should be returned immediately.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5375 \end{ctypedesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5376
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5377 The \member{tp_clear} handler must be of the \ctype{inquiry} type, or
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5378 \NULL{} if the object is immutable.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5379
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5380 \begin{ctypedesc}[inquiry]{int (*inquiry)(PyObject *self)}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5381 Drop references that may have created reference cycles. Immutable
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5382 objects do not have to define this method since they can never
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5383 directly create reference cycles. Note that the object must still
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5384 be valid after calling this method (don't just call
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5385 \cfunction{Py_DECREF()} on a reference). The collector will call
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5386 this method if it detects that this object is involved in a
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5387 reference cycle.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5388 \end{ctypedesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5389
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5390
17147
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5391 \subsection{Example Cycle Collector Support
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5392 \label{example-cycle-support}}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5393
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5394 This example shows only enough of the implementation of an extension
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5395 type to show how the garbage collector support needs to be added. It
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5396 shows the definition of the object structure, the
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5397 \member{tp_traverse}, \member{tp_clear} and \member{tp_dealloc}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5398 implementations, the type structure, and a constructor --- the module
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5399 initialization needed to export the constructor to Python is not shown
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5400 as there are no special considerations there for the collector. To
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5401 make this interesting, assume that the module exposes ways for the
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5402 \member{container} field of the object to be modified. Note that
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5403 since no checks are made on the type of the object used to initialize
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5404 \member{container}, we have to assume that it may be a container.
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5405
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5406 \begin{verbatim}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5407 #include "Python.h"
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5408
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5409 typedef struct {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5410 PyObject_HEAD
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5411 PyObject *container;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5412 } MyObject;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5413
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5414 static int
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5415 my_traverse(MyObject *self, visitproc visit, void *arg)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5416 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5417 if (self->container != NULL)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5418 return visit(self->container, arg);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5419 else
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5420 return 0;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5421 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5422
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5423 static int
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5424 my_clear(MyObject *self)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5425 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5426 Py_XDECREF(self->container);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5427 self->container = NULL;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5428
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5429 return 0;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5430 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5431
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5432 static void
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5433 my_dealloc(MyObject *self)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5434 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5435 PyObject_GC_Fini((PyObject *) self);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5436 Py_XDECREF(self->container);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5437 PyObject_Del(self);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5438 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5439 \end{verbatim}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5440
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5441 \begin{verbatim}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5442 statichere PyTypeObject
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5443 MyObject_Type = {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5444 PyObject_HEAD_INIT(NULL)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5445 0,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5446 "MyObject",
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5447 sizeof(MyObject) + PyGC_HEAD_SIZE,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5448 0,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5449 (destructor)my_dealloc, /* tp_dealloc */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5450 0, /* tp_print */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5451 0, /* tp_getattr */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5452 0, /* tp_setattr */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5453 0, /* tp_compare */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5454 0, /* tp_repr */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5455 0, /* tp_as_number */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5456 0, /* tp_as_sequence */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5457 0, /* tp_as_mapping */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5458 0, /* tp_hash */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5459 0, /* tp_call */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5460 0, /* tp_str */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5461 0, /* tp_getattro */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5462 0, /* tp_setattro */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5463 0, /* tp_as_buffer */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5464 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_GC,
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5465 0, /* tp_doc */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5466 (traverseproc)my_traverse, /* tp_traverse */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5467 (inquiry)my_clear, /* tp_clear */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5468 0, /* tp_richcompare */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5469 0, /* tp_weaklistoffset */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5470 };
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5471
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5472 /* This constructor should be made accessible from Python. */
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5473 static PyObject *
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5474 new_object(PyObject *unused, PyObject *args)
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5475 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5476 PyObject *container = NULL;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5477 MyObject *result = NULL;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5478
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5479 if (PyArg_ParseTuple(args, "|O:new_object", &container)) {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5480 result = PyObject_New(MyObject, &MyObject_Type);
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5481 if (result != NULL) {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5482 result->container = container;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5483 PyObject_GC_Init();
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5484 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5485 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5486 return (PyObject *) result;
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5487 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5488 \end{verbatim}
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5489
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5490
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5491 % \chapter{Debugging \label{debugging}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5492 %
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5493 % 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
5494
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
5495
14736
2b9a890162b0 Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents: 14696
diff changeset
5496 \appendix
2b9a890162b0 Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents: 14696
diff changeset
5497 \chapter{Reporting Bugs}
2b9a890162b0 Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents: 14696
diff changeset
5498 \input{reportingbugs}
2b9a890162b0 Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents: 14696
diff changeset
5499
18192
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
5500 \chapter{History and License}
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
5501 \input{license}
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
5502
15953
8349b4dfc51a Undoing the whitespace patches which sneaked into the earlier patch.
Marc-André Lemburg <mal@egenix.com>
parents: 15952
diff changeset
5503 \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
5504
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
5505 \end{document}