Mercurial > cpython-lru_cache-weakref

annotate Doc/api/api.tex @ 20010:d03c19db3094 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Document new file() constructor, with the body of open()'s text, plus a "new in 2.2" blurb at the end. Replace open()'s text by pointing back to file().
author Tim Peters <tim.peters@gmail.com>
date Thu, 20 Sep 2001 19:55:29 +0000
parents 0fe318a78990
children cd72b64aec97
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).
19771
432591328410 Document the rule that Python.h must be included before any standard
Fred Drake <fdrake@acm.org>
parents: 19735
diff changeset
79 Since Python may define some pre-processor definitions which affect
432591328410 Document the rule that Python.h must be included before any standard
Fred Drake <fdrake@acm.org>
parents: 19735
diff changeset
80 the standard headers on some systems, you must include \file{Python.h}
432591328410 Document the rule that Python.h must be included before any standard
Fred Drake <fdrake@acm.org>
parents: 19735
diff changeset
81 before any standard headers are included.
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
82
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
83 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
84 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
85 \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
86 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
87 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
88
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
89 \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
90 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
91 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
92 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
93 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
94
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
95 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
96 are located in the directories
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
97 \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
98 \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
99 \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
100 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
101 \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
102 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
103 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
104
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
105 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
106 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
107 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
108 \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
109 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
110 \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
111 \envvar{exec_prefix}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
112
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
113 \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
114 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
115 \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
116 the API from \Cpp.
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
117
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
118
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
119 \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
120
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 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
122 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
123 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
124 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
125 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
126 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
127 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
128 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
129 \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
130 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
131 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
132 \ctype{PyTypeObject} objects.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
133
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
134 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
135 \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
136 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
137 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
138 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
139 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
140 \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
141 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
142
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
143
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
144 \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
145
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
146 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
147 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
148 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
149 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
150 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
151 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
152 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
153 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
154 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
155 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
156 ``don't do that.'')
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
157
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
158 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
159 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
160 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
161 \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
162 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
163 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
164 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
165 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
166 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
167 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
168 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
169 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
170 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
171 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
172 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
173 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
174
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
175 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
176 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
177 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
178 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
179 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
180 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
181 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
182 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
183 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
184 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
185 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
186 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
187 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
188 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
189
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
190 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
191 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
192 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
193 list, decrementing its reference count and possible deallocating it.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
194 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
195 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
196 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
197 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
198
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
199 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
200 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
201 \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
202 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
203 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
204 \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
205 becomes second nature.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
206
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
207
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
208 \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
209
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 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
211 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
212 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
213 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
214 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
215 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
216 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
217 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
218 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
219 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
220
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
221 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
222 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
223 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
224 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
225 \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
226 \cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
227 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
228 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
229 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
230 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
231 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
232 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
233
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 \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
235 PyObject *t;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
236
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
237 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
238 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
239 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
240 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
241 \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
242
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
243 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
244 set tuple items; \cfunction{PySequence_SetItem()} and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
245 \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
246 immutable data type. You should only use
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
247 \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
248 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
249
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
250 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
251 \cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
252 can also use \cfunction{PySequence_SetItem()}; this illustrates the
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
253 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
254
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 \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
256 PyObject *l, *x;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
257
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 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
259 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
260 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
261 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
262 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
263 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
264 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
265 \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
266
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
267 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
268 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
269 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
270 \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
271 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
272 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
273 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
274
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 \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
276 PyObject *t, *l;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
277
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
278 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
279 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
280 \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
281
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
282 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
283 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
284 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
285 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
286 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
287 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
288 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
289 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
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 \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
292 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
293 {
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 int i, n;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
295
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
296 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
297 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
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 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
300 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
301 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
302 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
303 return 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
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 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
306 \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
307
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 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
309 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
310 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
311 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
312 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
313 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
314 object. Therefore, the generic functions that return object
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
315 references, like \cfunction{PyObject_GetItem()} and
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
316 \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
317 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
318
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
319 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
320 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
321 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
322 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
323 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
324 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
325 same list using \cfunction{PySequence_GetItem()} (which happens to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
326 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
327 returned object.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
328
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
329 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
330 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
331 \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
332 \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
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 \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
335 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
336 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
337 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
338 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
339 PyObject *item;
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
340
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
341 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
342 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
343 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
344 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
345 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
346 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
347 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
348 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
349 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
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 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
352 \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
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 \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
355 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
356 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
357 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
358 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
359 PyObject *item;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
360 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
361 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
362 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
363 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
364 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
365 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
366 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
367 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
368 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
369 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
370 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
371 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
372 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
373 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
374 \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
375
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
376
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
377 \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
378
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
379 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
380 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
381 \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
382 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
383 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
384 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
385 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
386
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
387
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
388 \section{Exceptions \label{exceptions}}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
389
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
390 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
391 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
392 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
393 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
394 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
395
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
396 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
397 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
398 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
399 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
400 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
401 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
402 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
403 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
404 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
405 \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
406
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
407 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
408 equivalent to using global storage in an unthreaded application). A
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
409 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
410 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
411 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
412 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
413 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
414 \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
415 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
416 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
417 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
418
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
419 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
420 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
421 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
422 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
423 \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
424 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
425 \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
426 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
427 \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
428 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
429 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
430 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
431 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
432
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
433 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
434 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
435 \withsubitem{(in module sys)}{\ttindex{exc_info()}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
436 \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
437 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
438 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
439 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
440 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
441 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
442 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
443 unwanted lifetime extension for objects that are referenced by the
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
444 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
445
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
446 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
447 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
448 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
449 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
450 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
451 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
452 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
453
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
454 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
455 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
456 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
457 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
458 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
459 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
460
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
461 \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
462 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
463 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
464 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
465 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
466 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
467 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
468 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
469 \ttindex{incr_item()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
470
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
471 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
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 \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
474 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
475 {
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 /* 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
477 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
478 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
479
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
480 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
481 if (item == NULL) {
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
482 /* 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
483 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
484 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
485
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
486 /* 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
487 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
488 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
489 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
490 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
491 }
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 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
493 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
494 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
495
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
496 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
497 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
498 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
499
7721fb509462 In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents: 15444
diff changeset
500 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
501 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
502 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
503 /* 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
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 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
506 /* 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
507
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 /* 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
509 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
510 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
511 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
512
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
513 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
514 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
515 \end{verbatim}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
516 \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
517
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
518 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
519 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
520 \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
521 \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
522 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
523 \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
524 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
525 \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
526 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
527 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
528 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
529 \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
530 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
531
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
532
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
533 \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
534
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
535 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
536 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
537 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
538 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
539 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
540
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
541 The basic initialization function is
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
542 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
543 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
544 fundamental modules \module{__builtin__}\refbimodindex{__builtin__},
19242
d99c1240d0ac Add "exceptions" to the list of fundamental modules
Fred Drake <fdrake@acm.org>
parents: 19156
diff changeset
545 \module{__main__}\refbimodindex{__main__}, \module{sys}\refbimodindex{sys},
d99c1240d0ac Add "exceptions" to the list of fundamental modules
Fred Drake <fdrake@acm.org>
parents: 19156
diff changeset
546 and \module{exceptions}.\refbimodindex{exceptions} It also initializes
d99c1240d0ac Add "exceptions" to the list of fundamental modules
Fred Drake <fdrake@acm.org>
parents: 19156
diff changeset
547 the module search path (\code{sys.path}).%
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
548 \indexiii{module}{search}{path}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
549 \withsubitem{(in module sys)}{\ttindex{path}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
550
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
551 \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
552 (\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
553 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
554 \code{PySys_SetArgv(\var{argc},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
555 \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
556 \cfunction{Py_Initialize()}.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
557
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
558 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
559 details are slightly different),
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
560 \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
561 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
562 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
563 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
564 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
565 \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
566 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
567 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
568
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
569 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
570 \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
571 \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
572 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
573 \file{python} is found along \envvar{PATH}.) The user can override
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
574 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
575 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
576 setting \envvar{PYTHONPATH}.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
577
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
578 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
579 \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
580 \cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
581 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
582 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
583 provide its own implementation of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
584 \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
585 \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
586 \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
587 \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
588 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
589
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
590 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
591 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
592 \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
593 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
594 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
595 \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
596 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
597 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
598
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
599
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
600 \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
601
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
602 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
603 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
604 more detailed way with the interpreter.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
605
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
606 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
607 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
608 \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
609 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
610
13959
8be7524085d6 In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents: 13929
diff changeset
611 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
612 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
613 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
614 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
615 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
616 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
617 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
618 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
619
17877
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
620 \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
621 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
622 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
623 \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
624 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
625 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
626 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
627 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
628 \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
629 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
630 represent a valid Python command line.
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
631 \end{cfuncdesc}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
632
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
633 \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
634 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
635 (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
636 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
637 result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
638 \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
639 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
640
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
641 \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
642 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
643 \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
644 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
645 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
646 get the exception information.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
647 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
648
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
649 \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
650 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
651 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
652 \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
653 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
654
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
655 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename}
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
656 Read and execute a single statement from a file associated with an
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
657 interactive device. If \var{filename} is \NULL, \code{"???"} is
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
658 used instead. The user will be prompted using \code{sys.ps1} and
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
659 \code{sys.ps2}. Returns \code{0} when the input was executed
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
660 successfully, \code{-1} if there was an exception, or an error code
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
661 from the \file{errcode.h} include file distributed as part of Python
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
662 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
663 included by \file{Python.h}, so must be included specifically if
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
664 needed.)
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
665 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
666
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
667 \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename}
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
668 Read and execute statements from a file associated with an
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
669 interactive device until \EOF{} is reached. If \var{filename} is
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
670 \NULL, \code{"???"} is used instead. The user will be prompted
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
671 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
672 \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
673
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
674 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
675 int start}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
676 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
677 \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
678 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
679 must be evaluated many times.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
680 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
681
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
682 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
683 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
684 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
685 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
686 \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
687 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
688
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
689 \begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
690 PyObject *globals,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
691 PyObject *locals}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
692 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
693 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
694 \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
695 the source code.
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
696
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
697 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
698 \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
699 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
700
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
701 \begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
702 int start, PyObject *globals,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
703 PyObject *locals}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
704 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
705 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
706 \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
707 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
708
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
709 \begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
710 int start}
10786
a34d6656f8e2 Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents: 10219
diff changeset
711 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
712 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
713 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
714 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
715 \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
716 \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
717 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
718 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
719 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
720
11222
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
721 \begin{cvardesc}{int}{Py_eval_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
722 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
723 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
724 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
725
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
726 \begin{cvardesc}{int}{Py_file_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
727 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
728 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
729 \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
730 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
731 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
732
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
733 \begin{cvardesc}{int}{Py_single_input}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
734 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
735 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
736 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
737 \end{cvardesc}
ecfe3d8cb0c3 Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents: 11176
diff changeset
738
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
739
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
740 \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
741
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
742 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
743 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
744
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
745 \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
746 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
747 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
748 \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
749 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
750
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
751 \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
752 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
753 \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
754 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
755
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
756 \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
757 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
758 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
759 \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
760 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
761 invoked.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
762
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
763 \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
764 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
765 \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
766 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
767 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
768 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
769 \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
770 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
771 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
772 \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
773 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
774
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
775 \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
776 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
777 \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
778 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
779 applies.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
780 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
781
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
782 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
783 interpreter core: \cfunction{_Py_Dealloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
784 \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
785 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
786
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
787
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
788 \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
789
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
790 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
791 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
792 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
793 \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
794 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
795 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
796 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
797 \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
798 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
799 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
800 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
801 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
802 already set it.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
803
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
804 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
805 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
806 \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
807 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
808 \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
809 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
810 for each thread.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
811
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
812 % 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
813 % 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
814
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
815 \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
816 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
817 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
818 (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
819 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
820
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
821 \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
822 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
823 \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
824 \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
825 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
826 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
827 \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
828 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
829 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
830 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
831 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
832 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
833
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
834 \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
835 Equivalent to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
836 \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
837 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
838 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
839 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
840
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
841 \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
842 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
843 \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
844 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
845 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
846 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
847 occur.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
848 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
849
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
850 \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
851 Under certain circumstances, the values returned by
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
852 \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
853 \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
854 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
855 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
856 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
857 performance.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
858 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
859
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
860 \begin{cfuncdesc}{void}{PyErr_Clear}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
861 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
862 is no effect.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
863 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
864
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
865 \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
866 PyObject **ptraceback}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
867 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
868 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
869 \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
870 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
871 \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
872 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
873 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
874 temporarily.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
875 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
876
14279
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
877 \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value,
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
878 PyObject *traceback}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
879 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
880 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
881 \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
882 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
883 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
884 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
885 (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
886 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
887 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
888 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
889 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
890 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
891 temporarily.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
892 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
893
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
894 \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
895 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
896 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
897 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
898 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
899 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
900 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
901
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
902 \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
903 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
904 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
905 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
906 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
907
12355
04802b7e8a1f Yet another markup nit: functions that are part of the Python/C API
Fred Drake <fdrake@acm.org>
parents: 12354
diff changeset
908 \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
909 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
910 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
911 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
912 \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
913 \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
914 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
915
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
916 \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
917 \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
918 \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
919 \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
920 \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
921 \end{tableii}
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
922
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
923 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
924 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
925 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
926
2de1fb5302ed Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents: 14337
diff changeset
927 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
928 \end{cfuncdesc}
54e80db49423 document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 12258
diff changeset
929
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
930 \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
931 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
932 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
933
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
934 \begin{cfuncdesc}{int}{PyErr_BadArgument}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
935 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
936 \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
937 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
938 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
939
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
940 \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
941 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
942 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
943 \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
944 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
945
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
946 \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
947 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
948 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
949 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
950 \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
951 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
952 then calls
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
953 \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
954 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
955 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
956 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
957 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
958 \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
959 error.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
960 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
961
18192
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
962 \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
963 char *filename}
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
964 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
965 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
966 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
967 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
968 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
969 instance.
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
970 \end{cfuncdesc}
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
971
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
972 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
973 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
974 \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
975 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
976 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
977 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
978
15613
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
979 \begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message}
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
980 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
981 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
982 string.
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
983
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
984 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
985 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
986 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
987 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
988 because of a problem with the warning machinery (the implementation
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
989 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
990 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
991 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
992 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
993 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
994 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
995 (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
996 value).
15613
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
997
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
998 Warning categories must be subclasses of \cdata{Warning}; the default
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
999 warning category is \cdata{RuntimeWarning}. The standard Python
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1000 warning categories are available as global variables whose names are
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1001 \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
1002 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
1003 \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning},
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1004 \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1005 \cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass of
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1006 \cdata{PyExc_Exception}; the other warning categories are subclasses
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1007 of \cdata{PyExc_Warning}.
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1008
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1009 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
1010 \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
1011 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
1012 \end{cfuncdesc}
35749a557f1e Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents: 15453
diff changeset
1013
16872
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1014 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message,
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1015 char *filename, int lineno, char *module, PyObject *registry}
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1016 Issue a warning message with explicit control over all warning
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1017 attributes. This is a straightforward wrapper around the Python
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1018 function \function{warnings.warn_explicit()}, see there for more
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1019 information. The \var{module} and \var{registry} arguments may be
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1020 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
1021 \end{cfuncdesc}
5280e8439d55 Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents: 16577
diff changeset
1022
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1023 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1024 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
1025 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
1026 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
1027 \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
1028 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
1029 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
1030 \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
1031 \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
1032 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
1033 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
1034 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
1035 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1036
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1037 \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
1038 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
1039 \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
1040 \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
1041 \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
1042 \exception{KeyboardInterrupt} will be raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1043 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
1044 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1045
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1046 \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1047 PyObject *base,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1048 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
1049 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
1050 \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
1051 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
1052 \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
1053 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
1054 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
1055 \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
1056 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
1057 \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
1058 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
1059 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
1060 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
1061 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1062
14330
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1063 \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
1064 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
1065 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
1066 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
1067 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
1068
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1069 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
1070 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
1071 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
1072 message.
6dee1985c681 refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents: 14279
diff changeset
1073 \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
1074
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1075 \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
1076
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1077 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
1078 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
1079 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
1080 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
1081
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1082 \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
1083 \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
1084 \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
1085 \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
1086 \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
1087 \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1088 \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1089 \lineiii{PyExc_EOFError}{\exception{EOFError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1090 \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
1091 \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1092 \lineiii{PyExc_IOError}{\exception{IOError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1093 \lineiii{PyExc_ImportError}{\exception{ImportError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1094 \lineiii{PyExc_IndexError}{\exception{IndexError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1095 \lineiii{PyExc_KeyError}{\exception{KeyError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1096 \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1097 \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1098 \lineiii{PyExc_NameError}{\exception{NameError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1099 \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1100 \lineiii{PyExc_OSError}{\exception{OSError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1101 \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1102 \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1103 \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1104 \lineiii{PyExc_SystemError}{\exception{SystemError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1105 \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1106 \lineiii{PyExc_TypeError}{\exception{TypeError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1107 \lineiii{PyExc_ValueError}{\exception{ValueError}}{}
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1108 \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
1109 \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1110 \end{tableiii}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1111
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1112 \noindent
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1113 Notes:
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1114 \begin{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1115 \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
1116 This is a base class for other standard exceptions.
13929
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1117
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1118 \item[(2)]
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1119 Only defined on Windows; protect code that uses this by testing that
f194d8b24865 PyRun_InteractiveOne(),
Fred Drake <fdrake@acm.org>
parents: 13920
diff changeset
1120 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
1121 \end{description}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1122
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1123
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1124 \section{Deprecation of String Exceptions}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1125
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 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
1127 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
1128 \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
1129
f1f4d822e761 Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents: 13053
diff changeset
1130 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
1131 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
1132 release.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1133
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1134
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1135 \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
1136
18785
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1137 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
1138 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
1139 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
1140 values from C values.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
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
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
1143 \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
1144
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1145 \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
1146 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
1147 \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
1148 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
1149 \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
1150 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
1151 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
1152 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1153
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1154 \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1155 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
1156 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
1157 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
1158 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1159
13053
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1160 \begin{cfuncdesc}{void}{PyOS_AfterFork}{}
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1161 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
1162 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
1163 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
1164 process, this function does not need to be called.
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1165 \end{cfuncdesc}
b00744237877 Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents: 12947
diff changeset
1166
14279
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1167 \begin{cfuncdesc}{int}{PyOS_CheckStack}{}
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1168 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
1169 reliable check, but is only available when \code{USE_STACKCHECK} is
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1170 defined (currently on Windows using the Microsoft Visual C++ compiler
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1171 and on the Macintosh). \code{USE_CHECKSTACK} will be defined
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1172 automatically; you should never change the definition in your own
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1173 code.
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1174 \end{cfuncdesc}
b1a0fd3df1fc Document PyOS_CheckStack().
Fred Drake <fdrake@acm.org>
parents: 13959
diff changeset
1175
14635
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1176 \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
1177 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
1178 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
1179 \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
1180 \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
1181 \end{cfuncdesc}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1182
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1183 \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
1184 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
1185 return the old signal handler.
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1186 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
1187 \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
1188 \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
1189 \end{cfuncdesc}
db9ea5b5f337 Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents: 14557
diff changeset
1190
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1191
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1192 \section{Process Control \label{processControl}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1193
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1194 \begin{cfuncdesc}{void}{Py_FatalError}{char *message}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1195 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
1196 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
1197 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
1198 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
1199 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
1200 \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
1201 produce a \file{core} file.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1202 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1203
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1204 \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
1205 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
1206 \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
1207 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
1208 \code{exit(\var{status})}\ttindex{exit()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1209 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1210
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1211 \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
1212 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
1213 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1214 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
1215 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
1216 functions can be registered.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1217 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
1218 \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
1219 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
1220 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
1221 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
1222 by \var{func}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1223 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1224
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1225
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1226 \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
1227
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1228 \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
1229 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
1230 \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
1231 \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
1232 \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
1233 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
1234 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
1235 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
1236 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
1237 \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
1238 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
1239 \index{package variable!\code{__all__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1240 \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
1241 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
1242 \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
1243 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
1244 \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
1245 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1246
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1247 \begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1248 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
1249 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
1250 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
1251 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
1252 directly.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1253
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1254 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
1255 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
1256 (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
1257 \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
1258 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
1259 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
1260 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1261
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1262 \begin{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
1263 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
1264 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
1265 \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
1266 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
1267 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
1268 \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
1269 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1270
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1271 \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
1272 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
1273 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
1274 \function{reload()} function calls this function directly. Return a
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1275 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
1276 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
1277 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1278
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1279 \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
1280 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
1281 \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
1282 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
1283 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
1284 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
1285 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
1286 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
1287 import a module.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1288 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
1289 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1290
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1291 \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
1292 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
1293 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
1294 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
1295 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
1296 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
1297 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
1298 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
1299 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1300
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1301 \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
1302 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
1303 \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
1304 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
1305 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
1306 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1307
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1308 \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
1309 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
1310 (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
1311 variable.
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_Init}{}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1315 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
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_Cleanup}{}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1319 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
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
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1322 \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
1323 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
1324 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1325
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1326 \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
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}
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
1329
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1330 \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
1331 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
1332 \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
1333
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
1334 \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name}
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
1335 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
1336 \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
1337 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
1338 successful load, use \cfunction{PyImport_ImportModule()}.
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1339 (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
1340 already imported.)
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1341 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1342
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1343 \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
1344 This is the structure type definition for frozen module descriptors,
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1345 as generated by the \program{freeze}\index{freeze utility} utility
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1346 (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
1347 definition, found in \file{Include/import.h}, is:
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1348
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1349 \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
1350 struct _frozen {
6480
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1351 char *name;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1352 unsigned char *code;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
1353 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
1354 };
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1355 \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
1356 \end{ctypedesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1357
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
1358 \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
1359 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
1360 _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
1361 \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
1362 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
1363 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
1364 \end{cvardesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1365
14337
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1366 \begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name,
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1367 void (*initfunc)(void)}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1368 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
1369 is a convenience wrapper around \cfunction{PyImport_ExtendInittab()},
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1370 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
1371 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
1372 \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
1373 attempted import. This should be called before
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1374 \cfunction{Py_Initialize()}.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1375 \end{cfuncdesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1376
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1377 \begin{ctypedesc}[_inittab]{struct _inittab}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1378 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
1379 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
1380 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
1381 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
1382 \cfunction{PyImport_ExtendInittab()} to provide additional built-in
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1383 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
1384
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1385 \begin{verbatim}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1386 struct _inittab {
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1387 char *name;
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1388 void (*initfunc)(void);
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1389 };
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1390 \end{verbatim}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1391 \end{ctypedesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1392
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1393 \begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1394 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
1395 \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
1396 \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
1397 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
1398 \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
1399 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
1400 internal table. This should be called before
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1401 \cfunction{Py_Initialize()}.
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1402 \end{cfuncdesc}
3b84c5ff89da Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents: 14330
diff changeset
1403
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1404
18785
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1405 \section{Parsing arguements and building values
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1406 \label{arg-parsing}}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1407
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1408 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
1409 and methods. Additional information and examples are available in
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1410 \citetitle[../ext/ext.html]{Extending and Embedding the Python
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1411 Interpreter}.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1412
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1413 \begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1414 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1415 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
1416 parameters into local variables. Returns true on success; on
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1417 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
1418 \citetitle[../ext/parseTuple.html]{Extending and Embedding the
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1419 Python Interpreter} for more information.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1420 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1421
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1422 \begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1423 PyObject *kw, char *format, char *keywords[],
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1424 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1425 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
1426 keyword parameters into local variables. Returns true on success;
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1427 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
1428 See \citetitle[../ext/parseTupleAndKeywords.html]{Extending and
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1429 Embedding the Python Interpreter} for more information.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1430 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1431
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1432 \begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1433 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1434 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
1435 functions --- these are functions which use the
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1436 \constant{METH_OLDARGS} parameter parsing method. This is not
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1437 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
1438 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
1439 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
1440 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
1441 purpose.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1442 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1443
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1444 \begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format,
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1445 \moreargs}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1446 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
1447 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
1448 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
1449 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
1450 information on the format string and additional parameters, see
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1451 \citetitle[../ext/buildValue.html]{Extending and Embedding the
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1452 Python Interpreter}.
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1453 \end{cfuncdesc}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1454
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1455
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
1456
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1457 \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
1458
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1459 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
1460 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
1461 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
1462 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
1463
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1464 \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
1465
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1466 \begin{cfuncdesc}{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
1467 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
1468 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
1469 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
1470 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
1471 \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
1472 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1473
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1474 \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
1475 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
1476 \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
1477 \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
1478 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
1479 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1480
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1481 \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
1482 char *attr_name}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1483 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
1484 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
1485 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1486 \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
1487 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1488
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1489
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1490 \begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1491 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
1492 \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
1493 \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
1494 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
1495 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1496
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1497
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1498 \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
1499 PyObject *attr_name}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1500 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
1501 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
1502 This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1503 \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
1504 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1505
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1506
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1507 \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1508 char *attr_name, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1509 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
1510 \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
1511 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
1512 \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
1513 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1514
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1515
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1516 \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1517 PyObject *attr_name, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1518 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
1519 object \var{o},
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1520 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
1521 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
1522 \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
1523 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1524
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 \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
1527 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
1528 \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
1529 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
1530 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1531
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 \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
1534 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
1535 \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
1536 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
1537 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1538
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1539
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1540 \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
1541 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
1542 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
1543 \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
1544 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
1545 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
1546 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1547
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1548
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1549 \begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1550 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
1551 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
1552 \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
1553 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
1554 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
1555 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
1556 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1557
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1558
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1559 \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
1560 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
1561 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
1562 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
1563 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
1564 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
1565 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1566
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1567
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1568 \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
1569 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
1570 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
1571 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
1572 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
1573 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
1574 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1575
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1576
15952
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1577 \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
1578 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
1579 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
1580 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
1581 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
1582 \end{cfuncdesc}
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1583
17242
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1584 \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
1585 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
1586 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
1587 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
1588 \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
1589 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
1590 \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
1591 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
1592 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
1593 \versionadded{2.1}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1594 \end{cfuncdesc}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1595
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1596 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
1597 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
1598 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
1599 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
1600 \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
1601 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
1602 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
1603 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
1604 \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
1605 \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
1606 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
1607 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
1608 determination.
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1609
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1610 \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
1611 PyObject *cls}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1612 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
1613 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
1614 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
1615 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
1616 described above.
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1617 \versionadded{2.1}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1618 \end{cfuncdesc}
1b12e6340038 Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents: 17209
diff changeset
1619
15952
1f92d63b20f0 This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents: 15733
diff changeset
1620
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1621 \begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1622 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
1623 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
1624 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
1625 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1626
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1627
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1628 \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
1629 PyObject *args}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1630 Call a callable Python object \var{callable_object}, with
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1631 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
1632 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
1633 call on success, or \NULL{} on failure. This is the equivalent
18944
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
1634 of the Python expression \samp{apply(\var{callable_object},
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
1635 \var{args})} or \samp{\var{callable_object}(*\var{args})}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
1636 \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
1637 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1638
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1639 \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
1640 char *format, ...}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1641 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
1642 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
1643 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
1644 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
1645 result of the call on success, or \NULL{} on failure. This is
18944
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
1646 the equivalent of the Python expression
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
1647 \samp{apply(\var{callable_object}\var{args})} or
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
1648 \samp{\var{callable_object}(*\var{args})}.
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
1649 \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
1650 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1651
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1652
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1653 \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
1654 char *method, char *format, ...}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1655 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
1656 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
1657 \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
1658 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
1659 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
1660 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
1661 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
1662 \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
1663 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
1664 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1665
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1666
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1667 \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1668 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
1669 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
1670 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
1671 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1674 \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1675 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
1676 \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
1677 \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
1678 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
1679 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1680
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1681
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1682 \begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
1683 When \var{o} is non-\NULL, returns a type object corresponding to the
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
1684 object type of object \var{o}. On failure, raises
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
1685 \exception{SystemError} and returns \NULL. This is equivalent to the
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
1686 Python expression \code{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
1687 \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
1688 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1689
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
1690 \begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
1691 Return true if the object \var{o} is of type \var{type} or a subtype
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
1692 of \var{type}. Both parameters must be non-\NULL.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
1693 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
1694
5536
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_Length}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1696 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
1697 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
1698 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
1699 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
1700 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1701
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1702
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1703 \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
1704 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
1705 \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
1706 \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
1707 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1708
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1709
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1710 \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1711 PyObject *key, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1712 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
1713 Returns \code{-1} on failure. This is the equivalent
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1714 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
1715 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1716
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1717
9931
00fc18ac6aeb Header for PyObject_DelItem() mentioned non-existing 3rd argument.
Guido van Rossum <guido@python.org>
parents: 9476
diff changeset
1718 \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
1719 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
1720 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
1721 \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
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
13592
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1724 \begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o}
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1725 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
1726 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
1727 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
1728 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
1729 descriptor value. Returns \code{-1} on failure.
9ca50e2433eb Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents: 13404
diff changeset
1730 \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
1731
19705
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1732 \begin{cfuncdesc}{PyObject*}{PyObject_Dir}{PyObject *o}
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1733 This is equivalent to the Python expression \samp{dir(\var{o})},
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1734 returning a (possibly empty) list of strings appropriate for the
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1735 object argument, or \NULL{} in case of error.
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1736 If the argument is \NULL{}, this is like the Python \samp{dir()},
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1737 returning the names of the current locals; in this case, if no
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1738 execution frame is active then \NULL{} is returned but
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1739 \cfunction{PyErr_Occurred()} will return false.
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1740 \end{cfuncdesc}
b7f6fbc087a7 At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents: 19607
diff changeset
1741
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1742
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
1743 \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
1744
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1745 \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1746 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
1747 false otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1748 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
1749 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1750
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1751
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1752 \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
1753 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
1754 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1755 \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
1756 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1757
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1758
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1759 \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
1760 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
1761 \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
1762 \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
1763 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1764
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1765
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1766 \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
1767 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
1768 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1769 \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
1770 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1771
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1772
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1773 \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
1774 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
1775 failure.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1776 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
1777 \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
1778 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1779
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1780
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1781 \begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1782 Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1783 failure. This is equivalent to the ``classic'' division of integers.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1784 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1785 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1786
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1787
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1788 \begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1789 Return a reasonable approximation for the mathematical value of
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1790 \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1791 is ``approximate'' because binary floating point numbers are
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1792 approximate; it is not possible to represent all real numbers in base
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1793 two. This function can return a floating point value when passed two
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1794 integers.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1795 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1796 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1797
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1798
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1799 \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
1800 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
1801 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
1802 \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
1803 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1804
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1805
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1806 \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
1807 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
1808 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
1809 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
1810 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1811
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1812
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1813 \begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1814 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
1815 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
1816 \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
1817 \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
1818 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
1819 (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
1820 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1821
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1822
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1823 \begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1824 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
1825 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
1826 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1827
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1828
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1829 \begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1830 Returns \var{o} on success, or \NULL{} on failure.
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1831 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
1832 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1833
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1834
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1835 \begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1836 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
1837 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
1838 \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
1839 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1840
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1841
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1842 \begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1843 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
1844 failure. This is the equivalent of the Python expression
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
1845 \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
1846 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1847
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1848
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1849 \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
1850 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
1851 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
1852 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
1853 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1854
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1855
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1856 \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
1857 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
1858 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
1859 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
1860 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1861
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1862
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1863 \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
1864 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
1865 \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
1866 \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
1867 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1868
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1869
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1870 \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
1871 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
1872 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
1873 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
1874 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1875
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1876 \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
1877 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
1878 \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
1879 \samp{\var{o1} | \var{o2}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1880 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1881
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_InPlaceAdd}{PyObject *o1, PyObject *o2}
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1884 Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1885 failure. The operation is done \emph{in-place} when \var{o1} supports
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1886 it. This is the equivalent of the Python statement \samp{\var{o1} +=
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1887 \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1888 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1889
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1890
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1891 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1892 PyObject *o2}
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1893 Returns the result of subtracting \var{o2} from \var{o1}, or
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1894 \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1895 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1896 \samp{\var{o1} -= \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1897 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1898
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1899
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1900 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1901 PyObject *o2}
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1902 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
1903 failure. The operation is done \emph{in-place} when \var{o1} supports it.
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1904 This is the equivalent of the Python statement \samp{\var{o1} *= \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1905 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1906
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1907
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1908 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1909 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1910 Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1911 failure. The operation is done \emph{in-place} when \var{o1} supports
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1912 it. This is the equivalent of the Python statement \samp{\var{o1} /=
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1913 \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1914 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1915
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1916
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1917 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1918 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1919 Returns the mathematical of dividing \var{o1} by \var{o2}, or \NULL{}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1920 on failure. The operation is done \emph{in-place} when \var{o1}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1921 supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1922 \samp{\var{o1} //= \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1923 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1924 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1925
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1926
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1927 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1928 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1929 Return a reasonable approximation for the mathematical value of
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1930 \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1931 is ``approximate'' because binary floating point numbers are
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1932 approximate; it is not possible to represent all real numbers in base
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1933 two. This function can return a floating point value when passed two
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1934 integers. The operation is done \emph{in-place} when \var{o1}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1935 supports it.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1936 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1937 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1938
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1939
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1940 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1941 PyObject *o2}
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1942 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
1943 failure. The operation is done \emph{in-place} when \var{o1} supports it.
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1944 This is the equivalent of the Python statement \samp{\var{o1} \%= \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1945 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1946
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1947
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1948 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1949 PyObject *o2, PyObject *o3}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1950 See the built-in function \function{pow()}.\bifuncindex{pow} Returns
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1951 \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1952 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1953 \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None}, or an
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1954 in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1955 otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1956 place (passing \NULL{} for \var{o3} would cause an illegal memory
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1957 access).
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1958 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1959
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1960 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1961 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1962 Returns the result of left shifting \var{o1} by \var{o2} on success,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1963 or \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1964 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1965 \samp{\var{o1} <\code{<=} \var{o2}}.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1966 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1967
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1968
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1969 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1970 PyObject *o2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1971 Returns the result of right shifting \var{o1} by \var{o2} on success,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1972 or \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1973 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1974 \samp{\var{o1} >\code{>=} \var{o2}}.
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1975 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1976
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1977
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1978 \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
1979 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
1980 and \NULL{} on failure. The operation is done \emph{in-place} when
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1981 \var{o1} supports it. This is the equivalent of the Python statement
16053
aca05d75d232 Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents: 15953
diff changeset
1982 \samp{\var{o1} \&= \var{o2}}.
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1983 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1984
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1985
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1986 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2}
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1987 Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1988 success, or \NULL{} on failure. The operation is done \emph{in-place}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1989 when \var{o1} supports it. This is the equivalent of the Python
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1990 statement \samp{\var{o1} \textasciicircum= \var{o2}}.
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1991 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1992
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
1993 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2}
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1994 Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1995 \NULL{} on failure. The operation is done \emph{in-place} when
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1996 \var{o1} supports it. This is the equivalent of the Python statement
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
1997 \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
1998 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1999
14769
aa18e5239b46 PyNumber_Coerce() returns an int, not a PyObject *.
Fred Drake <fdrake@acm.org>
parents: 14736
diff changeset
2000 \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
2001 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
2002 \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
2003 \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
2004 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
2005 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
2006 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
2007 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
2008 \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
2009 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
2010 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
2011 \bifuncindex{coerce}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2012 \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
2013
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2014 \begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2015 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
2016 \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
2017 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
2018 \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
2019
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2020 \begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2021 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
2022 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
2023 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
2024 \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
2025
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2026 \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
2027 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
2028 \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
2029 \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
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
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2033 \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
2034
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2035 \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
2036 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
2037 \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
2038 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2039
17307
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents: 17242
diff changeset
2040 \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
2041 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
2042 \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
2043 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
2044 \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
2045 \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
2046
17307
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents: 17242
diff changeset
2047 \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
2048 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
2049 \end{cfuncdesc}
288d805af142 Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents: 17242
diff changeset
2050
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2051 \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
2052 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
2053 failure. This is the equivalent of the Python
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2054 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
2055 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2056
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}{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
2059 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
2060 \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
2061 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
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
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
2064 \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1,
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
2065 PyObject *o2}
14528
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
2066 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
2067 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
2068 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
2069 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
2070
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
2071
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
2072 \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
2073 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
2074 \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
2075 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
2076 *= \var{count}}.
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
2077 \end{cfuncdesc}
7366bb95f212 Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents: 14526
diff changeset
2078
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2079
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2080 \begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2081 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
2082 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
2083 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2084
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2085
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2086 \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
2087 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
2088 \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
2089 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
2090 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2091
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2092
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2093 \begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2094 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
2095 Returns \code{-1} on failure. This is the equivalent of the Python
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2096 statement \samp{\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
2097 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2098
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2099 \begin{cfuncdesc}{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
2100 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
2101 \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
2102 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
2103 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2104
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2105 \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
2106 int i2, PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2107 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
2108 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
2109 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
2110 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2111
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2112 \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
2113 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
2114 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
2115 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
2116 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2117
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2118 \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2119 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
2120 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
2121 \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
2122 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2123
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2124 \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
2125 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
2126 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
2127 \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
2128 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
2129 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2130
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2131 \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
2132 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
2133 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
2134 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
2135 \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
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 \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
2139 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
2140 \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
2141 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
2142 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2143
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2144 \begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2145 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
2146 \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
2147 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2148
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2149 \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2150 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
2151 \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
2152 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
2153 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
2154
7493
6857acbe2e74 Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents: 7467
diff changeset
2155
14519
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2156 \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
2157 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
2158 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
2159 \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
2160 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
2161 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
2162 \end{cfuncdesc}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2163
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2164 \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
2165 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
2166 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
2167 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
2168 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
2169 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
2170 \end{cfuncdesc}
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2171
7435331b48ee Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents: 14347
diff changeset
2172
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2173 \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
2174
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2175 \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
2176 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
2177 \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
2178 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2179
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2180
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2181 \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
2182 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
2183 \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
2184 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
2185 \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
2186 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2187
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2188
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2189 \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
2190 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
2191 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2192 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
2193 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2194
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2195
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2196 \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
2197 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
2198 Return \code{-1} on failure. This is equivalent to
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2199 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
2200 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2201
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2202
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2203 \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
2204 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
2205 \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
2206 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
2207 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
2208 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2209
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2210
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2211 \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
2212 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
2213 \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
2214 \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
2215 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
2216 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2217
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2218
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2219 \begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2220 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
2221 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
2222 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
2223 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2224
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2225
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2226 \begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2227 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
2228 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
2229 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
2230 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2231
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2232
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2233 \begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2234 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
2235 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
2236 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
2237 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
2238 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2239
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2240
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2241 \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
2242 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
2243 \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
2244 \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
2245 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2246
17695
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2247 \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
2248 PyObject *v}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
2249 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
2250 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
2251 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
2252 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2253
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2254
17695
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2255 \section{Iterator Protocol \label{iterator}}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2256
17696
ffc2923bad1a Hmm... better add a version annotation for the Iterator Protocol section.
Fred Drake <fdrake@acm.org>
parents: 17695
diff changeset
2257 \versionadded{2.2}
ffc2923bad1a Hmm... better add a version annotation for the Iterator Protocol section.
Fred Drake <fdrake@acm.org>
parents: 17695
diff changeset
2258
17695
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2259 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
2260 iterators.
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2261
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2262 \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
2263 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
2264 \end{cfuncdesc}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2265
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2266 \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
2267 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
2268 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
2269 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
2270 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
2271 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
2272 \NULL{} and passes along the exception.
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2273 \end{cfuncdesc}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2274
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2275 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
2276 look something like this:
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2277
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2278 \begin{verbatim}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2279 PyObject *iterator = ...;
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2280 PyObject *item;
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2281
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2282 while (item = PyIter_Next(iter)) {
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2283 /* do something with item */
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2284 }
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2285 if (PyErr_Occurred()) {
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2286 /* propogate error */
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2287 }
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2288 else {
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2289 /* continue doing useful work */
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2290 }
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2291 \end{verbatim}
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2292
1e902fc73645 Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents: 17618
diff changeset
2293
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2294 \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
2295
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2296 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
2297 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
2298 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
2299 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
2300 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
2301 \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
2302 ``family tree'' of Python object types.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2303
15300
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2304 \strong{Warning:}
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2305 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
2306 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
2307 \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
2308 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
2309 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
2310
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2311
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2312 \section{Fundamental Objects \label{fundamental}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2313
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2314 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
2315 \code{None}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2316
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2317
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2318 \subsection{Type Objects \label{typeObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2319
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2320 \obindex{type}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2321 \begin{ctypedesc}{PyTypeObject}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2322 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
2323 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2324
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2325 \begin{cvardesc}{PyObject*}{PyType_Type}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2326 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
2327 \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
2328 \withsubitem{(in module types)}{\ttindex{TypeType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2329 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2330
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2331 \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
2332 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
2333 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2334
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2335 \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
2336 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
2337 \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
2338 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2339
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2340
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2341 \subsection{The None Object \label{noneObject}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2342
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2343 \obindex{None@\texttt{None}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2344 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
2345 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
2346 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
2347 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
2348
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2349 \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
2350 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
2351 no methods.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2352 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2353
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2354
18481
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2355 \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
2356
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2357 \obindex{numeric}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2358
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2359
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2360 \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
2361
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2362 \obindex{integer}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2363 \begin{ctypedesc}{PyIntObject}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2364 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
2365 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2366
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2367 \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
2368 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
2369 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
2370 \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
2371 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2372
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2373 \begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2374 Returns true if \var{o} is of type \cdata{PyInt_Type} or a subtype of
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2375 \cdata{PyInt_Type}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2376 \versionchanged[Allowed subtypes to be accepted]{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2377 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2378
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2379 \begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject* o}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2380 Returns true if \var{o} is of type \cdata{PyInt_Type}, but not a
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2381 subtype of \cdata{PyInt_Type}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2382 \versionadded{2.2}
18481
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2383 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2384
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2385 \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
2386 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
2387
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2388 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
2389 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
2390 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
2391 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
2392 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
2393 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2394
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2395 \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
2396 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
2397 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
2398 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2399
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2400 \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
2401 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
2402 performed.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2403 \end{cfuncdesc}
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}{long}{PyInt_GetMax}{}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2406 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
2407 (\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
2408 header files).
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2409 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2410
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2411
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2412 \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
2413
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2414 \obindex{long integer}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2415 \begin{ctypedesc}{PyLongObject}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2416 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
2417 object.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2418 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2419
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2420 \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
2421 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
2422 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
2423 \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
2424 \end{cvardesc}
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 \begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2427 Returns true if its argument is a \ctype{PyLongObject} or a subtype of
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2428 \ctype{PyLongObject}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2429 \versionchanged[Allowed subtypes to be accepted]{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2430 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2431
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2432 \begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2433 Returns true if its argument is a \ctype{PyLongObject}, but not a
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2434 subtype of \ctype{PyLongObject}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2435 \versionadded{2.2}
18481
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2436 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2437
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2438 \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
2439 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
2440 failure.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2441 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2442
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2443 \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
2444 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
2445 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
2446 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2447
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2448 \begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2449 Returns a new \ctype{PyLongObject} object from a C \ctype{long long},
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2450 or \NULL{} on failure.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2451 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2452
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2453 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2454 Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2455 long long}, or \NULL{} on failure.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2456 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2457
18481
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2458 \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
2459 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
2460 \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
2461 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2462
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2463 \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
2464 int base}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2465 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
2466 \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
2467 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
2468 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
2469 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
2470 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
2471 \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
2472 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
2473 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
2474 \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
2475 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
2476 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2477
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2478 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u,
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2479 int length, int base}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2480 Convert a sequence of Unicode digits to a Python long integer value.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2481 The first parameter, \var{u}, points to the first character of the
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2482 Unicode string, \var{length} gives the number of characters, and
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2483 \var{base} is the radix for the conversion. The radix must be in the
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2484 range [2, 36]; if it is out of range, \exception{ValueError} will be
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2485 raised.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2486 \versionadded{1.6}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2487 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2488
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2489 \begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2490 Create a Python integer or long integer from the pointer \var{p}. The
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2491 pointer value can be retrieved from the resulting value using
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2492 \cfunction{PyLong_AsVoidPtr()}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2493 \versionadded{1.5.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2494 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2495
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2496 \begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2497 Returns a C \ctype{long} representation of the contents of
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2498 \var{pylong}. If \var{pylong} is greater than
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2499 \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2500 raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2501 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2502
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2503 \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2504 Returns a C \ctype{unsigned long} representation of the contents of
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2505 \var{pylong}. If \var{pylong} is greater than
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2506 \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2507 is raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2508 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2509
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2510 \begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2511 Return a C \ctype{long long} from a Python long integer. If
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2512 \var{pylong} cannot be represented as a \ctype{long long}, an
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2513 \exception{OverflowError} will be raised.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2514 \versionadded{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2515 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2516
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2517 \begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2518 *pylong}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2519 Return a C \ctype{unsigned long long} from a Python long integer. If
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2520 \var{pylong} cannot be represented as an \ctype{unsigned long long},
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2521 an \exception{OverflowError} will be raised if the value is positive,
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2522 or a \exception{TypeError} will be raised if the value is negative.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2523 \versionadded{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2524 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2525
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2526 \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2527 Returns a C \ctype{double} representation of the contents of
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2528 \var{pylong}. If \var{pylong} cannot be approximately represented as
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2529 a \ctype{double}, an \exception{OverflowError} exception is raised and
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2530 \code{-1.0} will be returned.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2531 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2532
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2533 \begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2534 Convert a Python integer or long integer \var{pylong} to a C
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2535 \ctype{void} pointer. If \var{pylong} cannot be converted, an
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2536 \exception{OverflowError} will be raised. This is only assured to
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2537 produce a usable \ctype{void} pointer for values created with
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2538 \cfunction{PyLong_FromVoidPtr()}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2539 \versionadded{1.5.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2540 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2541
18481
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2542
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2543 \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
2544
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2545 \obindex{floating point}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2546 \begin{ctypedesc}{PyFloatObject}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2547 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
2548 object.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2549 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2550
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2551 \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
2552 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
2553 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
2554 \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
2555 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2556
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2557 \begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2558 Returns true if its argument is a \ctype{PyFloatObject} or a subtype
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2559 of \ctype{PyFloatObject}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2560 \versionchanged[Allowed subtypes to be accepted]{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2561 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2562
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2563 \begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2564 Returns true if its argument is a \ctype{PyFloatObject}, but not a
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2565 subtype of \ctype{PyFloatObject}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2566 \versionadded{2.2}
18481
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2567 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2568
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2569 \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
2570 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
2571 failure.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2572 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2573
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2574 \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
2575 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
2576 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2577
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2578 \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
2579 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
2580 \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
2581 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2582
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2583
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2584 \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
2585
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2586 \obindex{complex number}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2587 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
2588 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
2589 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
2590 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
2591 with both.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2592
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2593 \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
2594
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2595 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
2596 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
2597 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
2598 the API.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2599
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2600 \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
2601 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
2602 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
2603 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
2604 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
2605
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2606 \begin{verbatim}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2607 typedef struct {
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2608 double real;
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2609 double imag;
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2610 } Py_complex;
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2611 \end{verbatim}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2612 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2613
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2614 \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
2615 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
2616 \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
2617 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2618
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2619 \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
2620 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
2621 \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
2622 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2623
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2624 \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
2625 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
2626 \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
2627 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2628
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2629 \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
2630 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
2631 \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
2632 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2633
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2634 \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
2635 Py_complex divisor}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2636 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
2637 \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
2638 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2639
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2640 \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
2641 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
2642 \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
2643 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2644
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2645
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2646 \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
2647
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2648 \begin{ctypedesc}{PyComplexObject}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2649 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
2650 \end{ctypedesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2651
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2652 \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
2653 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
2654 number type.
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2655 \end{cvardesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2656
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2657 \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2658 Returns true if its argument is a \ctype{PyComplexObject} or a subtype
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2659 of \ctype{PyComplexObject}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2660 \versionchanged[Allowed subtypes to be accepted]{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2661 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2662
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2663 \begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2664 Returns true if its argument is a \ctype{PyComplexObject}, but not a
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2665 subtype of \ctype{PyComplexObject}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2666 \versionadded{2.2}
18481
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2667 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2668
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2669 \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
2670 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
2671 \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
2672 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2673
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2674 \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
2675 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
2676 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2677
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2678 \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
2679 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
2680 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2681
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2682 \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
2683 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
2684 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2685
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2686 \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
2687 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
2688 \end{cfuncdesc}
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2689
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2690
795aa4590211 Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents: 18447
diff changeset
2691
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2692 \section{Sequence Objects \label{sequenceObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2693
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2694 \obindex{sequence}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2695 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
2696 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
2697 objects that are intrinsic to the Python language.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2698
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2699
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
2700 \subsection{String Objects \label{stringObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2701
15300
0da4ccc7e8cf Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents: 15236
diff changeset
2702 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
2703 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
2704
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2705 \obindex{string}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2706 \begin{ctypedesc}{PyStringObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
2707 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
2708 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2709
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2710 \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
2711 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
2712 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
2713 layer.\withsubitem{(in module types)}{\ttindex{StringType}}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2714 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2715
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2716 \begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2717 Returns true if the object \var{o} is a string object or an instance
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2718 of a subtype of the string type.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2719 \versionchanged[Allowed subtypes to be accepted]{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2720 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2721
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2722 \begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2723 Returns true if the object \var{o} is a string object, but not an
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2724 instance of a subtype of the string type.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2725 \versionadded{2.2}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2726 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2727
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2728 \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
2729 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
2730 \NULL{} on failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2731 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2732
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2733 \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
2734 int len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2735 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
2736 \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
2737 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
2738 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2739
19524
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2740 \begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2741 Takes a C \code{printf}-style \var{format} string and a variable
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2742 number of arguments, calculates the size of the resulting Python
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2743 string and returns a string with the values formatted into it. The
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2744 variable arguments must be C types and must correspond exactly to the
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2745 format characters in the \var{format} string. The following format
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2746 characters are allowed:
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2747 \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2748 \lineiii{\%\%}{\emph{n/a}}{The literal \% character.}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2749 \lineiii{\%c}{int}{A single character, represented as an C int.}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2750 \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2751 \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2752 \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2753 \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2754 \lineiii{\%s}{char*}{A null-terminated C character array.}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2755 \lineiii{\%p}{void*}{The hex representation of a C pointer.
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2756 Mostly equivalent to \code{printf("\%p")} except that it is
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2757 guaranteed to start with the literal \code{0x} regardless of
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2758 what the platform's \code{printf} yields.}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2759 \end{tableiii}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2760 \end{cfuncdesc}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2761
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2762 \begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format,
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2763 va_list vargs}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2764 Identical to \function{PyString_FromFormat()} except that it takes
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2765 exactly two arguments.
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2766 \end{cfuncdesc}
ab194f1f053b Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents: 19399
diff changeset
2767
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2768 \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
2769 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
2770 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2771
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2772 \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
2773 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
2774 checking.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2775 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2776
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2777 \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
2778 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
2779 \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
2780 \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
2781 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
2782 \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
2783 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
2784 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2785
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
2786 \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
2787 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
2788 checking.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2789 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2790
14696
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2791 \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
2792 char **buffer,
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2793 int *length}
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2794 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
2795 \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
2796
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2797 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
2798 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
2799 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
2800 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
2801 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
2802
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2803 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
2804 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
2805 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
2806 \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
2807 \end{cfuncdesc}
85038a024b19 This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents: 14635
diff changeset
2808
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2809 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2810 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
2811 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
2812 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
2813 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
2814 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
2815 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
2816 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
2817 \NULL{}; the appropriate exception will be set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2818 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2819
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2820 \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2821 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
2822 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
2823 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
2824 the reference count of \var{newpart}.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2825 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2826
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2827 \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
2828 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
2829 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
2830 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
2831 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2832
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2833 \begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2834 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
2835 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
2836 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
2837 a tuple.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2838 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2839
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2840 \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
2841 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
2842 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
2843 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
2844 \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
2845 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
2846 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
2847 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
2848 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
2849 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
2850 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
2851 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2852
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2853 \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
2854 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
2855 \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
2856 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
2857 interned string object with the same value.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2858 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
2859
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2860 \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
2861 int size,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2862 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2863 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
2864 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
2865 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
2866 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
2867 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
2868 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
2869 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
2870 codec.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2871 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2872
17835
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2873 \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
2874 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
2875 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
2876 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
2877 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
2878 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
2879 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
2880 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
2881 \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
2882 \end{cfuncdesc}
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2883
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2884 \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
2885 int size,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2886 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2887 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
2888 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
2889 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
2890 \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
2891 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
2892 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
2893 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
2894 codec.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2895 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2896
17835
9ea87c0a7c04 This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents: 17696
diff changeset
2897 \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
2898 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2899 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
2900 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
2901 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
2902 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
2903 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
2904 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
2905 \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
2906 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
2907
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2908
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2909 \subsection{Unicode Objects \label{unicodeObjects}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2910 \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com}
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 %--- Unicode Type -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2913
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2914 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
2915 implementation in Python:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2916
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2917 \begin{ctypedesc}{Py_UNICODE}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2918 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
2919 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
2920 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
2921 \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
2922 native platform compatibility. On all other platforms,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2923 \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
2924 \end{ctypedesc}
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 \begin{ctypedesc}{PyUnicodeObject}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2927 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
2928 \end{ctypedesc}
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 \begin{cvardesc}{PyTypeObject}{PyUnicode_Type}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2931 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
2932 \end{cvardesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2933
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2934 %--- 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
2935
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2936 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
2937 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
2938
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2939 \begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2940 Returns true if the object \var{o} is a Unicode object or an instance
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2941 of a Unicode subtype.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2942 \versionchanged[Allowed subtypes to be accepted]{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2943 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2944
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2945 \begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2946 Returns true if the object \var{o} is a Unicode object, but not an
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2947 instance of a subtype.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
2948 \versionadded{2.2}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2949 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2950
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2951 \begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2952 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
2953 PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2954 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2955
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2956 \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
2957 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
2958 a PyUnicodeObject (not checked).
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
12932
1fa7c119b7a5 Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support.
Fred Drake <fdrake@acm.org>
parents: 12930
diff changeset
2961 \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
2962 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
2963 has to be a PyUnicodeObject (not checked).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2964 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2965
12932
1fa7c119b7a5 Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support.
Fred Drake <fdrake@acm.org>
parents: 12930
diff changeset
2966 \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
2967 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
2968 o has to be a PyUnicodeObject (not checked).
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 % --- Unicode character properties ---------------------------------------
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 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
2974 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
2975 functions depending on the Python configuration.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2976
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2977 \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
2978 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
2979 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2980
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2981 \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
2982 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
2983 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2984
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2985 \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
2986 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
2987 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2988
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2989 \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
2990 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
2991 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2992
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
2993 \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
2994 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
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 \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
2998 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
2999 \end{cfuncdesc}
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}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3002 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
3003 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3004
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3005 \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
3006 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
3007 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3008
13321
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
3009 \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
3010 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
3011 \end{cfuncdesc}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
3012
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
3013 \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
3014 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
3015 \end{cfuncdesc}
ac24d82d8e33 Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 13217
diff changeset
3016
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3017 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
3018
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3019 \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
3020 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
3021 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3022
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3023 \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
3024 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
3025 \end{cfuncdesc}
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 \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
3028 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
3029 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3030
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3031 \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
3032 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
3033 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
3034 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3035
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3036 \begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3037 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
3038 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
3039 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3040
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3041 \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
3042 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
3043 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
3044 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3045
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3046 % --- Plain Py_UNICODE ---------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3047
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3048 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
3049 use these APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3050
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3051 \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
3052 int size}
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 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
3055 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
3056 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
3057 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
3058 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
3059 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
3060 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3061
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3062 \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
3063 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
3064 \ctype{Py_UNICODE} buffer.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3065 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3066
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3067 \begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3068 Return the length of the Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3069 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3070
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
3071 \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
3072 const char *encoding,
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
3073 const char *errors}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
3074
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
3075 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
3076 reference with incremented refcount.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3077
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3078 Coercion is done in the following way:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3079 \begin{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3080 \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
3081 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
3082 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
3083
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3084 \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
3085 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
3086 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
3087 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
3088
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
3089 \item All other objects cause an exception.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3090 \end{enumerate}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3091 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
3092 for decref'ing the returned objects.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3093 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3094
13404
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
3095 \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
3096
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
3097 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
3098 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
3099 Unicode is needed.
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
3100 \end{cfuncdesc}
4cf21852fd52 Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents: 13321
diff changeset
3101
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3102 % --- wchar_t support for platforms which support it ---------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3103
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3104 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
3105 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
3106 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
3107 \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
3108
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3109 \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
3110 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3111 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
3112 given size. Returns \NULL{} on failure.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3113 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3114
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3115 \begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3116 wchar_t *w,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3117 int size}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3118 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
3119 \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
3120 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
3121 of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3122 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3123
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3124
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3125 \subsubsection{Builtin Codecs \label{builtinCodecs}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3126
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3127 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
3128 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
3129 following functions.
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 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
3132 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
3133 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
3134
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3135 Setting encoding to NULL causes the default encoding to be used which
19735
f56c91820fae Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents: 19705
diff changeset
3136 is \ASCII{}. The file system calls should use
f56c91820fae Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents: 19705
diff changeset
3137 \var{Py_FileSystemDefaultEncoding} as the encoding for file
f56c91820fae Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents: 19705
diff changeset
3138 names. This variable should be treated as read-only: On some systems,
f56c91820fae Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents: 19705
diff changeset
3139 it will be a pointer to a static string, on others, it will change at
f56c91820fae Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents: 19705
diff changeset
3140 run-time, e.g. when the application invokes setlocale.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3141
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3142 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
3143 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
3144 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
3145
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3146 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
3147 following generic ones are documented for simplicity.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3148
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3149 % --- Generic Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3150
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3151 These are the generic codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3152
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3153 \begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3154 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3155 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3156 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3157 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
3158 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
3159 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
3160 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
3161 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
3162 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3163 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3164
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3165 \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
3166 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3167 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3168 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3169 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
3170 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
3171 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
3172 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
3173 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
3174 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3175 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3176
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3177 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3178 const char *encoding,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3179 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3180 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
3181 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
3182 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
3183 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
3184 \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
3185 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3186
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3187 % --- UTF-8 Codecs -------------------------------------------------------
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 These are the UTF-8 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3190
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3191 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3192 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3193 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3194 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
3195 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
3196 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3197 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3198
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3199 \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
3200 int size,
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 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
3203 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
3204 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_AsUTF8String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3208 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
3209 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3210 \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
3211 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3212
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3213 % --- UTF-16 Codecs ------------------------------------------------------ */
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3214
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3215 These are the UTF-16 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3216
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3217 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3218 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3219 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3220 int *byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3221 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
3222 returns the corresponding Unicode object.
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 \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
3225 to ``strict''.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3226
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3227 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
3228 the given byte order:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3229
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3230 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3231 *byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3232 *byteorder == 0: native order
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3233 *byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3234 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3235
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3236 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
3237 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
3238 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
3239 order at the end of input data.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3240
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3241 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
3242
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3243 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
3244 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3245
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3246 \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
3247 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3248 const char *errors,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3249 int byteorder}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3250 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
3251 Unicode data in \var{s}.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3252
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
3253 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
3254 following byte order:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3255
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3256 \begin{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3257 byteorder == -1: little endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3258 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
3259 byteorder == 1: big endian
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3260 \end{verbatim}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3261
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
3262 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
3263 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
3264 prepended.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3265
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3266 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
3267 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
3268 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
3269
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3270 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
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 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3274 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
3275 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
3276 ``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
3277 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3278 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3279
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3280 % --- Unicode-Escape Codecs ----------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3281
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3282 These are the ``Unicode Esacpe'' codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3283
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3284 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3285 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3286 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3287 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
3288 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
3289 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3290 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3291
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3292 \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
3293 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3294 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3295 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
3296 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
3297 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3298 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3299
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3300 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3301 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
3302 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
3303 \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
3304 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3305
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3306 % --- Raw-Unicode-Escape Codecs ------------------------------------------
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 These are the ``Raw Unicode Esacpe'' codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3309
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3310 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3311 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3312 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3313 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
3314 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
3315 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3316 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3317
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3318 \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
3319 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3320 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3321 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
3322 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
3323 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3324 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3325
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3326 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3327 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
3328 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
3329 \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
3330 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3331
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3332 % --- Latin-1 Codecs -----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3333
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3334 These are the Latin-1 codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3335
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3336 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
3337 are accepted by the codecs during encoding.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3338
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3339 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3340 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3341 const char *errors}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3342 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
3343 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
3344 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3345 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3346
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3347 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3348 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3349 const char *errors}
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3350 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
3351 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
3352 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3353 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3354
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3355 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3356 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
3357 Python string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3358 \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
3359 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3360
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3361 % --- ASCII Codecs -------------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3362
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3363 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
3364 accepted. All other codes generate errors.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3365
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3366 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3367 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3368 const char *errors}
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3369 Creates a Unicode object by decoding \var{size} bytes of the
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3370 \ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3371 was raised by the codec.
12258
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_EncodeASCII}{const Py_UNICODE *s,
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3375 int size,
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3376 const char *errors}
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3377 Encodes the \ctype{Py_UNICODE} buffer of the given size using
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3378 \ASCII{} and returns a Python string object. Returns \NULL{} in case
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3379 an exception was raised by the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3380 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3381
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3382 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3383 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
3384 string object. Error handling is ``strict''. Returns
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3385 \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
3386 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3387
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3388 % --- Character Map Codecs -----------------------------------------------
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 These are the mapping codec APIs:
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3391
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3392 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
3393 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
3394 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
3395 codec uses mapping to encode and decode characters.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3396
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3397 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
3398 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
3399 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
3400
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3401 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
3402 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
3403 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
3404
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3405 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
3406 interface.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3407
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3408 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
3409 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
3410 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
3411 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
3412 points.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3413
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3414 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3415 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3416 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3417 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3418 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
3419 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
3420 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
3421 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3422
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3423 \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
3424 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3425 PyObject *mapping,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3426 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3427 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
3428 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
3429 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
3430 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3431
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3432 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3433 PyObject *mapping}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3434 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
3435 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
3436 ``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
3437 codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3438 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3439
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3440 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
3441
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3442 \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
3443 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3444 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3445 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3446 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
3447 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
3448 Unicode object. Returns \NULL{} when an exception was raised by the
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3449 codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3450
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3451 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
3452 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
3453
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3454 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3455 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
3456 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
3457 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3458
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3459 % --- MBCS codecs for Windows --------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3460
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3461 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
3462 Windows and use the Win32 MBCS converters to implement the
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3463 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
3464 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
3465 machine running the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3466
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3467 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3468 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3469 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3470 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
3471 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
3472 raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3473 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3474
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3475 \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
3476 int size,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3477 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3478 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
3479 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
3480 exception was raised by the codec.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3481 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3482
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3483 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3484 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
3485 string object. Error handling is ``strict''. Returns \NULL{} in case
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3486 an exception was raised by the codec.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3487 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3488
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3489 % --- Methods & Slots ----------------------------------------------------
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3490
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3491 \subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3492
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3493 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
3494 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
3495 Unicode objects or integers as apporpriate.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3496
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3497 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
3498
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3499 \begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3500 PyObject *right}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3501 Concat two strings giving a new Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3502 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3503
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3504 \begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3505 PyObject *sep,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3506 int maxsplit}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3507 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
3508
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3509 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
3510 substrings. Otherwise, splits occur at the given separator.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3511
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3512 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
3513
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3514 Separators are not included in the resulting list.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3515 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3516
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3517 \begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3518 int maxsplit}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3519 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
3520 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
3521 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
3522 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3523
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3524 \begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3525 PyObject *table,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3526 const char *errors}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3527 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
3528 return the resulting Unicode object.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3529
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3530 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
3531 integers or None (causing deletion of the character).
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3532
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3533 Mapping tables must only provide the __getitem__ interface,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3534 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
3535 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
3536
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3537 \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
3538 which indicates to use the default error handling.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3539 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3540
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3541 \begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3542 PyObject *seq}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3543 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
3544 the resulting Unicode string.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3545 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3546
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3547 \begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3548 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3549 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3550 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3551 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3552 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
3553 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
3554 \var{direction} == 1 a suffix match), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3555 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3556
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3557 \begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3558 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3559 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3560 int end,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3561 int direction}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3562 Return the first position of \var{substr} in
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3563 \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
3564 (\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
3565 \var{direction} == -1 a backward search), 0 otherwise.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3566 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3567
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3568 \begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3569 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3570 int start,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3571 int end}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3572 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
3573 \var{str}[\var{start}:\var{end}]
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3574 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3575
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3576 \begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3577 PyObject *substr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3578 PyObject *replstr,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3579 int maxcount}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3580 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
3581 \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
3582 \var{maxcount} == -1 means: replace all occurrences.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3583 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3584
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3585 \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
3586 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
3587 greater than resp.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3588 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3589
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3590 \begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3591 PyObject *args}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3592 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
3593 analogous to \code{\var{format} \%\ \var{args}}. The
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3594 \var{args} argument must be a tuple.
12258
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3595 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3596
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3597 \begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container,
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3598 PyObject *element}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3599 Checks whether \var{element} is contained in \var{container} and
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3600 returns true or false accordingly.
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3601
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
3602 \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
3603 returned in case of an error.
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3604 \end{cfuncdesc}
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3605
65bc5eaf47ce Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents: 12222
diff changeset
3606
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3607 \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
3608 \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
3609
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3610 \obindex{buffer}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3611 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
3612 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
3613 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
3614 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
3615 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
3616
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3617 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
3618 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
3619 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
3620 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
3621 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
3622
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3623 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
3624 \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
3625 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
3626 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
3627 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
3628 object.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3629
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3630 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
3631 ``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
3632 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
3633
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3634 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
3635 (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
3636 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
3637 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
3638 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
3639 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
3640 interface.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3641
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3642 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
3643 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
3644 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
3645 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
3646 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
3647 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
3648 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
3649 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
3650 format.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3651
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3652 \begin{ctypedesc}{PyBufferObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3653 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
3654 \end{ctypedesc}
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3655
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3656 \begin{cvardesc}{PyTypeObject}{PyBuffer_Type}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3657 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
3658 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
3659 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
3660 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3661
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3662 \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
3663 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
3664 \cfunction{PyBuffer_FromObject()} or
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3665 \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
3666 \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
3667 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
3668 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
3669 length.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3670 \end{cvardesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3671
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3672 \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
3673 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
3674 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3675
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3676 \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
3677 int offset, int size}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3678 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
3679 \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
3680 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
3681 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
3682 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
3683 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
3684 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
3685 \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
3686 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
3687 \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
3688 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3689
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3690 \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
3691 int offset,
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3692 int size}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3693 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
3694 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
3695 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
3696 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
3697 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3698
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3699 \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
3700 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
3701 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
3702 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
3703 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
3704 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
3705 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
3706 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
3707 that case.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3708 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3709
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3710 \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
3711 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
3712 is writable.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3713 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3714
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3715 \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
3716 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
3717 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
3718 \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
3719 \end{cfuncdesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
3720
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3721
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3722 \subsection{Tuple Objects \label{tupleObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3723
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3724 \obindex{tuple}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3725 \begin{ctypedesc}{PyTupleObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3726 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
3727 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3728
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3729 \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
3730 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
3731 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
3732 layer.\withsubitem{(in module types)}{\ttindex{TupleType}}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3733 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3734
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3735 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
3736 Return true if \var{p} is a tuple object or an instance of a subtype
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
3737 of the tuple type.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
3738 \versionchanged[Allowed subtypes to be accepted]{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
3739 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
3740
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
3741 \begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
3742 Return true if \var{p} is a tuple object, but not an instance of
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
3743 a subtype of the tuple type.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
3744 \versionadded{2.2}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3745 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3746
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3747 \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
3748 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
3749 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3750
16577
068cb8494b7b PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents: 16439
diff changeset
3751 \begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3752 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
3753 of that tuple.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3754 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3755
19399
e851e6148ad8 Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents: 19301
diff changeset
3756 \begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p}
e851e6148ad8 Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents: 19301
diff changeset
3757 Return the size of the tuple \var{p}, which must be non-\NULL{} and
e851e6148ad8 Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents: 19301
diff changeset
3758 point to a tuple; no error checking is performed.
e851e6148ad8 Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents: 19301
diff changeset
3759 \end{cfuncdesc}
e851e6148ad8 Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents: 19301
diff changeset
3760
16577
068cb8494b7b PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents: 16439
diff changeset
3761 \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
3762 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
3763 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
3764 sets an \exception{IndexError} exception.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3765 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3766
16577
068cb8494b7b PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents: 16439
diff changeset
3767 \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
3768 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
3769 arguments.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3770 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3771
16577
068cb8494b7b PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents: 16439
diff changeset
3772 \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
3773 int low, int high}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3774 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
3775 \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
3776 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3777
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3778 \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
3779 int pos, PyObject *o}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
3780 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
3781 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
3782 \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
3783 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3784
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3785 \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
3786 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
3787 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
3788 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
3789 \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
3790 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3791
17981
a2b996c716a1 Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents: 17877
diff changeset
3792 \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
3793 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
3794 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
3795 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
3796 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
3797 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
3798 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
3799 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
3800 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
3801 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
3802 \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
3803 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
3804 \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
3805 \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
3806 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3807
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3808
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3809 \subsection{List Objects \label{listObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3810
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3811 \obindex{list}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3812 \begin{ctypedesc}{PyListObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3813 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
3814 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3815
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3816 \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
3817 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
3818 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
3819 \withsubitem{(in module types)}{\ttindex{ListType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3820 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3821
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3822 \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
3823 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
3824 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3825
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3826 \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
3827 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
3828 failure.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3829 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3830
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3831 \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
3832 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
3833 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
3834 \bifuncindex{len}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3835 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3836
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3837 \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
3838 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
3839 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3840
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3841 \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
3842 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
3843 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
3844 sets an \exception{IndexError} exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3845 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3846
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3847 \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
3848 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
3849 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3850
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3851 \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3852 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
3853 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
3854 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
3855 \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
3856 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
3857 position.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3858 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3859
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3860 \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
3861 PyObject *o}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3862 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
3863 \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
3864 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
3865 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
3866 \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
3867 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
3868 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3869
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3870 \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
3871 PyObject *item}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
3872 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
3873 \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
3874 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
3875 \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
3876 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3877
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3878 \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
3879 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
3880 \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
3881 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
3882 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3883
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3884 \begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3885 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
3886 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
3887 \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
3888 exception if unsuccessful.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3889 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
3890 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3891
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3892 \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3893 int low, int high,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3894 PyObject *itemlist}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3895 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
3896 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
3897 \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
3898 \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
3899 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3900
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3901 \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
3902 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
3903 \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
3904 \samp{\var{list}.sort()}.
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3905 \end{cfuncdesc}
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3906
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3907 \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
3908 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
3909 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
3910 \samp{\var{list}.reverse()}.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3911 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3912
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3913 \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
3914 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
3915 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
3916 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3917
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3918
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3919 \section{Mapping Objects \label{mapObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3920
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3921 \obindex{mapping}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3922
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3923
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
3924 \subsection{Dictionary Objects \label{dictObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3925
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3926 \obindex{dictionary}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3927 \begin{ctypedesc}{PyDictObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
3928 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
3929 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3930
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3931 \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
3932 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
3933 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
3934 \code{types.DictionaryType}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3935 \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
3936 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3937
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3938 \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
3939 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
3940 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3941
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
3942 \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
3943 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
3944 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3945
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3946 \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
3947 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
3948 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3949
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
3950 \begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p}
19399
e851e6148ad8 Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents: 19301
diff changeset
3951 Returns a new dictionary that contains the same key-value pairs as
e851e6148ad8 Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents: 19301
diff changeset
3952 \var{p}.
19156
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
3953 \versionadded{1.6}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3954 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3955
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3956 \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
3957 PyObject *val}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3958 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
3959 \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
3960 raised.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3961 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
3962 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3963
17057
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
3964 \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p,
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3965 char *key,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
3966 PyObject *val}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3967 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
3968 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
3969 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
3970 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
3971 \ttindex{PyString_FromString()}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3972 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3973
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3974 \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
3975 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
3976 \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
3977 raised.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3978 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3979
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3980 \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
3981 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
3982 specified by the string \var{key}.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
3983 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
3984 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3985
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3986 \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
3987 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
3988 \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
3989 \emph{without} setting an exception.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3990 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3991
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3992 \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
3993 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
3994 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
3995 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3996
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
3997 \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
3998 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
3999 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
4000 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
4001 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4002
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4003 \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
4004 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
4005 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
4006 \citetitle[../lib/lib.html]{Python Library Reference}).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4007 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4008
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4009 \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
4010 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
4011 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
4012 \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
4013 Reference}).
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4014 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4015
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4016 \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
4017 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
4018 \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
4019 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4020
17057
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
4021 \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
4022 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
4023 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
4024 \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
4025 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
4026 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
4027 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
4028 \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
4029 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
4030 \NULL.
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4031
17057
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
4032 For example:
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
4033
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
4034 \begin{verbatim}
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
4035 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
4036 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
4037
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
4038 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
4039 /* 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
4040 ...
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
4041 }
797ebb7033d7 Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents: 16872
diff changeset
4042 \end{verbatim}
17504
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4043
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4044 The dictionary \var{p} should not be mutated during iteration. It is
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4045 safe (since Python 2.1) to modify the values of the keys as you
19156
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4046 iterate over the dictionary, but only so long as the set of keys does
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4047 not change. For example:
17504
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4048
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4049 \begin{verbatim}
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4050 PyObject *key, *value;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4051 int pos = 0;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4052
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4053 while (PyDict_Next(self->dict, &pos, &key, &value)) {
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4054 int i = PyInt_AS_LONG(value) + 1;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4055 PyObject *o = PyInt_FromLong(i);
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4056 if (o == NULL)
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4057 return -1;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4058 if (PyDict_SetItem(self->dict, key, o) < 0) {
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4059 Py_DECREF(o);
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4060 return -1;
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4061 }
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4062 Py_DECREF(o);
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4063 }
8e1415ef9b28 Michael Hudson:
Fred Drake <fdrake@acm.org>
parents: 17480
diff changeset
4064 \end{verbatim}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4065 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4066
19156
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4067 \begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4068 Iterate over dictionary \var{b} adding key-value pairs to dictionary
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4069 \var{a}. If \var{override} is true, existing pairs in \var{a} will be
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4070 replaced if a matching key is found in \var{b}, otherwise pairs will
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4071 only be added if there is not a matching key in \var{a}. Returns
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4072 \code{0} on success or \code{-1} if an exception was raised.
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4073 \versionadded{2.2}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4074 \end{cfuncdesc}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4075
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4076 \begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4077 This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C, or
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4078 \code{\var{a}.update(\var{b})} in Python. Returns \code{0} on success
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4079 or \code{-1} if an exception was raised.
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4080 \versionadded{2.2}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4081 \end{cfuncdesc}
776628eea8f7 Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents: 19126
diff changeset
4082
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4083
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4084 \section{Other Objects \label{otherObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4085
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4086 \subsection{File Objects \label{fileObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4087
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4088 \obindex{file}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4089 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
4090 \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
4091 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
4092
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4093 \begin{ctypedesc}{PyFileObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
4094 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
4095 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4096
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4097 \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
4098 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
4099 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
4100 \withsubitem{(in module types)}{\ttindex{FileType}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4101 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4102
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4103 \begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4104 Returns true if its argument is a \ctype{PyFileObject} or a subtype of
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4105 \ctype{PyFileObject}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4106 \versionchanged[Allowed subtypes to be accepted]{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4107 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4108
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4109 \begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4110 Returns true if its argument is a \ctype{PyFileObject}, but not a
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4111 subtype of \ctype{PyFileObject}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4112 \versionadded{2.2}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4113 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4114
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4115 \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
4116 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
4117 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
4118 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
4119 \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
4120 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4121
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4122 \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
4123 char *name, char *mode,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4124 int (*close)(FILE*)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4125 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
4126 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
4127 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
4128 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4129
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4130 \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
4131 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
4132 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4133
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4134 \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
4135 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
4136 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
4137 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
4138 \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
4139 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
4140 \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
4141 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
4142 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
4143 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
4144 \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
4145 immediately.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4146 \withsubitem{(built-in exception)}{\ttindex{EOFError}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4147 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4148
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4149 \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
4150 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
4151 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4152
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4153 \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
4154 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
4155 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
4156 creation.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4157 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4158
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4159 \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
4160 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
4161 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
4162 \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
4163 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
4164 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
4165 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
4166 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
4167 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
4168 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
4169 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
4170 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4171
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4172 \begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p,
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4173 int flags}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4174 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
4175 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
4176 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
4177 \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
4178 failure; the appropriate exception will be set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4179 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4180
19126
67be3a68fde4 Remove the bogus flags parameter from the PyFile_WriteString() signature;
Fred Drake <fdrake@acm.org>
parents: 19076
diff changeset
4181 \begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4182 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
4183 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
4184 set.
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4185 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4186
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4187
16318
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4188 \subsection{Instance Objects \label{instanceObjects}}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4189
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4190 \obindex{instance}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4191 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
4192
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4193 \begin{cvardesc}{PyTypeObject}{PyInstance_Type}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4194 Type object for class instances.
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4195 \end{cvardesc}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4196
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4197 \begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4198 Returns true if \var{obj} is an instance.
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4199 \end{cfuncdesc}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4200
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4201 \begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class,
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4202 PyObject *arg,
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4203 PyObject *kw}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4204 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
4205 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
4206 the object's constructor.
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4207 \end{cfuncdesc}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4208
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4209 \begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class,
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4210 PyObject *dict}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4211 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
4212 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
4213 \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
4214 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
4215 \end{cfuncdesc}
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4216
17cac70cae76 Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents: 16053
diff changeset
4217
19775
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4218 \subsection{Method Objects \label{method-objects}}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4219
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4220 \obindex{method}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4221 There are some useful functions that are useful for working with
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4222 method objects.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4223
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4224 \begin{cvardesc}{PyTypeObject}{PyMethod_Type}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4225 This instance of \ctype{PyTypeObject} represents the Python method
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4226 type. This is exposed to Python programs as \code{types.MethodType}.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4227 \withsubitem{(in module types)}{\ttindex{MethodType}}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4228 \end{cvardesc}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4229
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4230 \begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4231 Return true if \var{o} is a method object (has type
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4232 \cdata{PyMethod_Type}). The parameter must not be \NULL.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4233 \end{cfuncdesc}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4234
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4235 \begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4236 PyObject *self, PyObject *class}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4237 Return a new method object, with \var{func} being any callable
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4238 object; this is the function that will be called when the method is
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4239 called. If this method should be bound to an instance, \var{self}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4240 should be the instance and \var{class} should be the class of
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4241 \var{self}, otherwise \var{self} should be \NULL{} and \var{class}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4242 should be the class which provides the unbound method..
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4243 \end{cfuncdesc}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4244
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4245 \begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4246 Return the class object from which the method \var{meth} was
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4247 created; if this was created from an instance, it will be the class
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4248 of the instance.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4249 \end{cfuncdesc}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4250
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4251 \begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4252 Macro version of \cfunction{PyMethod_Class()} which avoids error
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4253 checking.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4254 \end{cfuncdesc}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4255
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4256 \begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4257 Return the function object associated with the method \var{meth}.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4258 \end{cfuncdesc}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4259
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4260 \begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4261 Macro version of \cfunction{PyMethod_Function()} which avoids error
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4262 checking.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4263 \end{cfuncdesc}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4264
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4265 \begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4266 Return the instance associated with the method \var{meth} if it is
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4267 bound, otherwise return \NULL.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4268 \end{cfuncdesc}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4269
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4270 \begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4271 Macro version of \cfunction{PyMethod_Self()} which avoids error
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4272 checking.
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4273 \end{cfuncdesc}
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4274
ee12c38e46a6 Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents: 19771
diff changeset
4275
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4276 \subsection{Module Objects \label{moduleObjects}}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4277
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4278 \obindex{module}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4279 There are only a few functions special to module objects.
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4280
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4281 \begin{cvardesc}{PyTypeObject}{PyModule_Type}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4282 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
4283 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
4284 \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
4285 \end{cvardesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4286
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4287 \begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p}
20009
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4288 Returns true if \var{p} is a module object, or a subtype of a
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4289 module object.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4290 \versionchanged[Allowed subtypes to be accepted]{2.2}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4291 \end{cfuncdesc}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4292
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4293 \begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p}
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4294 Returns true if \var{p} is a module object, but not a subtype of
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4295 \cdata{PyModule_Type}.
0fe318a78990 Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents: 19775
diff changeset
4296 \versionadded{2.2}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4297 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4298
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4299 \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
4300 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
4301 \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
4302 \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
4303 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
4304 \withsubitem{(module attribute)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4305 \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
4306 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4307
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4308 \begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4309 Return the dictionary object that implements \var{module}'s namespace;
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4310 this object is the same as the \member{__dict__} attribute of the
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4311 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
4312 \withsubitem{(module attribute)}{\ttindex{__dict__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4313 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4314
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4315 \begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4316 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
4317 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
4318 raised and \NULL{} is returned.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4319 \withsubitem{(module attribute)}{\ttindex{__name__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4320 \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
4321 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4322
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4323 \begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4324 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
4325 \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
4326 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
4327 \NULL.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4328 \withsubitem{(module attribute)}{\ttindex{__file__}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4329 \withsubitem{(built-in exception)}{\ttindex{SystemError}}
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4330 \end{cfuncdesc}
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4331
14782
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4332 \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
4333 char *name, PyObject *value}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4334 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
4335 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
4336 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
4337 \code{0} on success.
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4338 \versionadded{2.0}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4339 \end{cfuncdesc}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4340
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4341 \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
4342 char *name, int value}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4343 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
4344 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
4345 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
4346 \versionadded{2.0}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4347 \end{cfuncdesc}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4348
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4349 \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
4350 char *name, char *value}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4351 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
4352 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
4353 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
4354 error, \code{0} on success.
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4355 \versionadded{2.0}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4356 \end{cfuncdesc}
3c01f921c453 Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents: 14769
diff changeset
4357
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4358
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4359 \subsection{CObjects \label{cObjects}}
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4360
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4361 \obindex{CObject}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4362 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
4363 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
4364 information on using these objects.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4365
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4366
8109
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
4367 \begin{ctypedesc}{PyCObject}
8120
068fea15cbcd Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents: 8109
diff changeset
4368 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
4369 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
4370 \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
4371 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
4372 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
4373 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
4374 \end{ctypedesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
4375
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4376 \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
4377 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
4378 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4379
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4380 \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
4381 void (*destr)(void *)}
12947
6b2ecd172203 Markup consistency nits.
Fred Drake <fdrake@acm.org>
parents: 12932
diff changeset
4382 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
4383 \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
4384 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
4385 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
4386
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4387 \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
4388 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
4389 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
4390 \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
4391 \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
4392 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
4393 \end{cfuncdesc}
2e49bc89fafa Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents: 8057
diff changeset
4394
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4395 \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
4396 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
4397 \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
4398 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4399
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4400 \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
4401 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
4402 \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
4403 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4404
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
4405
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4406 \chapter{Initialization, Finalization, and Threads
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4407 \label{initialization}}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4408
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4409 \begin{cfuncdesc}{void}{Py_Initialize}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4410 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
4411 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
4412 functions; with the exception of
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4413 \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
4414 \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
4415 \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
4416 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
4417 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
4418 \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
4419 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
4420 \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
4421 \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
4422 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
4423 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
4424 \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
4425 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
4426 \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
4427 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
4428 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
4429
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
4430 \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
4431 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
4432 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
4433 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
4434 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4435 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4436
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4437 \begin{cfuncdesc}{void}{Py_Finalize}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4438 Undo all initializations made by \cfunction{Py_Initialize()} and
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4439 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
4440 sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4441 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
4442 \cfunction{Py_Initialize()}. Ideally, this frees all memory allocated
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4443 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
4444 time (without calling \cfunction{Py_Initialize()} again first). There
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4445 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
4446
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4447 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
4448 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
4449 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
4450 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
4451 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
4452 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
4453 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
4454
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4455 \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
4456 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
4457 (\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
4458 (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
4459 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
4460 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
4461 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
4462 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
4463 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
4464 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
4465 calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4466 than once.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4467 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4468
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4469 \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
4470 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
4471 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
4472 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
4473 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
4474 \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
4475 \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
4476 \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
4477 (\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
4478 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
4479 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
4480 \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
4481 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
4482 \withsubitem{(in module sys)}{
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4483 \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
4484
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4485 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
4486 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
4487 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
4488 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
4489 \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
4490 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
4491 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
4492 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
4493 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
4494 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
4495
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4496 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
4497 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
4498 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
4499 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
4500 (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
4501 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
4502 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
4503 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
4504 re-initialized by calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4505 \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
4506 \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
4507 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
4508 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4509
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4510 \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
4511 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
4512 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
4513 \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
4514 \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
4515 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
4516 (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
4517 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
4518 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
4519 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
4520 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
4521 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
4522 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
4523 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
4524 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
4525 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
4526 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4527
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4528 \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
4529 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
4530 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
4531 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
4532 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
4533 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
4534 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
4535 \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
4536 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
4537 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4538
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4539 \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
4540 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
4541 \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
4542 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
4543 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
4544 \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
4545 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
4546 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
4547 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
4548 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
4549 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
4550 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
4551 the contents of this storage.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4552 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4553
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4554 \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
4555 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
4556 \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
4557 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
4558 should not modify its value.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4559 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4560
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4561 \begin{cfuncdesc}{char*}{Py_GetPrefix}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4562 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
4563 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
4564 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
4565 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
4566 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
4567 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
4568 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
4569 \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
4570 \program{configure} script at build time. The value is available to
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
4571 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
4572 also the next function.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4573 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4574
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4575 \begin{cfuncdesc}{char*}{Py_GetExecPrefix}{}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4576 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
4577 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
4578 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
4579 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
4580 \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
4581 \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
4582 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
4583 \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
4584 \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
4585 \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
4586 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
4587
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4588 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
4589 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
4590 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
4591 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
4592 \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
4593 installed in \file{/usr/local}.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4594
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4595 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
4596 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
4597 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
4598 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
4599 Linux are yet another platform. Different major revisions of the same
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
4600 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
4601 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
4602 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
4603 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
4604 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
4605 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
4606
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4607 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
4608 \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
4609 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
4610 platform.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4611 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4612
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4613 \begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4614 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
4615 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
4616 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
4617 \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
4618 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
4619 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
4620 \code{sys.executable}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4621 \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
4622 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4623
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4624 \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
4625 \indexiii{module}{search}{path}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4626 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
4627 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
4628 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
4629 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
4630 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
4631 DOS/Windows, and \character{\e n} (the \ASCII{} newline character) on
7271
0061d3916ae4 "ASCII" --> "\ASCII{}"
Fred Drake <fdrake@acm.org>
parents: 7269
diff changeset
4632 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
4633 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
4634 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
4635 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
4636 modules.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4637
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4638 % XXX should give the exact rules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4639 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4640
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4641 \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
4642 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
4643 looks something like
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4644
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
4645 \begin{verbatim}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4646 "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
4647 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4648
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4649 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
4650 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
4651 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
4652 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
4653 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
4654 \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
4655 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4656
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4657 \begin{cfuncdesc}{const char*}{Py_GetPlatform}{}
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
4658 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
4659 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
4660 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
4661 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
4662 \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
4663 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
4664 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
4665 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
4666 \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
4667 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4668
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4669 \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
4670 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
4671 for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4672
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
4673 \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
4674
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4675 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
4676 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
4677 \code{sys.copyright}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4678 \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
4679 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4680
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4681 \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
4682 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
4683 version, in square brackets, for example:
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4684
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4685 \begin{verbatim}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4686 "[GCC 2.7.2.2]"
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4687 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4688
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4689 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
4690 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
4691 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
4692 \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
4693 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4694
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4695 \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
4696 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
4697 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
4698
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
4699 \begin{verbatim}
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
4700 "#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
4701 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4702
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4703 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
4704 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
4705 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
4706 \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
4707 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4708
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4709 \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
4710 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
4711 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
4712 \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
4713 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
4714 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
4715 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
4716 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
4717 condition is signalled using
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4718 \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
4719 \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
4720 % 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
4721 % check w/ Guido.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4722 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4723
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4724 % 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
4725
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4726 \section{Thread State and the Global Interpreter Lock
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
4727 \label{threads}}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4728
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4729 \index{global interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4730 \index{interpreter lock}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4731 \index{lock, interpreter}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4732
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4733 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
4734 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
4735 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
4736 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
4737 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
4738 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
4739 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
4740
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4741 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
4742 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
4743 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
4744 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
4745 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
4746 \withsubitem{(in module sys)}{\ttindex{setcheckinterval()}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4747 \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
4748 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
4749 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
4750 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
4751
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4752 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
4753 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
4754 \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
4755 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
4756 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
4757 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
4758 \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
4759 \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
4760 current thread.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4761
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4762 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
4763 \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
4764 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
4765 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
4766 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
4767 manipulated explicitly.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4768
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4769 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
4770 interpreter lock has the following simple structure:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4771
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4772 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4773 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
4774 Release the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4775 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4776 Reacquire the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4777 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
4778 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4779
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4780 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
4781
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4782 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4783 Py_BEGIN_ALLOW_THREADS
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4784 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4785 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
4786 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4787
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4788 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
4789 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
4790 \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
4791 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
4792 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
4793 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
4794
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4795 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
4796 following code:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4797
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4798 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4799 PyThreadState *_save;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4800
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4801 _save = PyEval_SaveThread();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4802 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4803 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
4804 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4805
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4806 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
4807 as follows:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4808
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4809 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4810 PyThreadState *_save;
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4811
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4812 _save = PyThreadState_Swap(NULL);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4813 PyEval_ReleaseLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4814 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4815 PyEval_AcquireLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4816 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
4817 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4818
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4819 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
4820 \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
4821 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
4822 \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
4823 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
4824 is disabled,
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4825 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4826 \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
4827 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
4828 \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
4829 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
4830 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
4831 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
4832
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4833 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
4834 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
4835 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
4836 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
4837 lock and store its own thread state in the global variable).
14926
76c1e40c5c5d Reversely --> Conversely
Fred Drake <fdrake@acm.org>
parents: 14870
diff changeset
4838 Conversely, when acquiring the lock and restoring the thread state,
76c1e40c5c5d Reversely --> Conversely
Fred Drake <fdrake@acm.org>
parents: 14870
diff changeset
4839 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
4840
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4841 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
4842 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
4843 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
4844 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
4845 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
4846 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
4847 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
4848 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
4849 structure.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4850
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4851 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
4852 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
4853 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
4854 interpreter, for example the module administration
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4855 (\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
4856 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
4857 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
4858 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
4859 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
4860 thread after Python is initialized).
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4861
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4862
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4863 \begin{ctypedesc}{PyInterpreterState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4864 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
4865 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
4866 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
4867 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
4868
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4869 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
4870 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
4871 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
4872 regardless of to which interpreter they belong.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4873 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4874
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4875 \begin{ctypedesc}{PyThreadState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4876 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
4877 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
4878 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
4879 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4880
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4881 \begin{cfuncdesc}{void}{PyEval_InitThreads}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4882 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
4883 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
4884 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
4885 \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
4886 \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
4887 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
4888 \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
4889 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4890
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4891 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
4892 this function before calling
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4893 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4894
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4895 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
4896 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
4897 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
4898 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
4899 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
4900 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
4901 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
4902 \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
4903 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
4904 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
4905 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
4906 has acquired it.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4907
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4908 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
4909 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
4910
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4911 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
4912 compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4913 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4914
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4915 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4916 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
4917 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
4918 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
4919 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4920 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4921
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4922 \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4923 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
4924 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
4925 disabled at compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4926 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4927
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4928 \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
4929 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
4930 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
4931 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
4932 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
4933 is disabled at compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4934 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4935
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4936 \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
4937 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
4938 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
4939 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
4940 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
4941 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
4942 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
4943 time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4944 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4945
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
4946 \begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4947 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
4948 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
4949 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
4950 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
4951 (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
4952 compile time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4953 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4954
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4955 \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4956 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
4957 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
4958 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
4959 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
4960 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
4961 time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4962 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
4963
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4964 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
4965 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
4966
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4967 \begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4968 This macro expands to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4969 \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4970 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
4971 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
4972 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
4973 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4974 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4975
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4976 \begin{csimplemacrodesc}{Py_END_ALLOW_THREADS}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4977 This macro expands to
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
4978 \samp{PyEval_RestoreThread(_save); \}}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4979 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
4980 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
4981 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
4982 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4983 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4984
18438
05c49346b68b Fix for SF bug #436525, reported by Greg Kochanski:
Thomas Wouters <thomas@python.org>
parents: 18192
diff changeset
4985 \begin{csimplemacrodesc}{Py_BLOCK_THREADS}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4986 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
4987 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
4988 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
4989 time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4990 \end{csimplemacrodesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4991
18438
05c49346b68b Fix for SF bug #436525, reported by Greg Kochanski:
Thomas Wouters <thomas@python.org>
parents: 18192
diff changeset
4992 \begin{csimplemacrodesc}{Py_UNBLOCK_THREADS}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
4993 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
4994 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
4995 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
4996 disabled at compile time.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
4997 \end{csimplemacrodesc}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4998
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
4999 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
5000 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
5001 interpreter lock has been created.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5002
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
5003 \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
5004 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
5005 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
5006 function.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
5007 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
5008
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5009 \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5010 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
5011 lock must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5012 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5013
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5014 \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5015 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
5016 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
5017 call to \cfunction{PyInterpreterState_Clear()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5018 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5019
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
5020 \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
5021 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
5022 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
5023 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
5024 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5025
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5026 \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5027 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
5028 must be held.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
5029 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
5030
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5031 \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5032 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
5033 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
5034 call to \cfunction{PyThreadState_Clear()}.
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5035 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5036
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
5037 \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5038 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
5039 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
5040 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
5041 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5042
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
5043 \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
5044 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
5045 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
5046 must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5047 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5048
17877
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
5049 \begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
5050 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
5051 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
5052 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
5053 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
5054 propogate.
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
5055 \end{cfuncdesc}
13bdb5b207d2 Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents: 17875
diff changeset
5056
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
5057
18671
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5058 \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
5059
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5060 \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
5061
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5062 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
5063 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
5064 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
5065
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5066 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
5067 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
5068 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
5069 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
5070 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
5071 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
5072 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
5073 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
5074 previous versions.
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5075
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5076 \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
5077 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
5078 PyObject *arg)}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5079 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
5080 \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
5081 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
5082 function,
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5083 \end{ctypedesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5084
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5085 \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
5086 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
5087 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
5088 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5089
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5090 \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
5091 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5092
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5093 \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
5094 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
5095 (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
5096 reported.
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5097 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5098
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5099 \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
5100 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
5101 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
5102 \end{cvardesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5103
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5104 \begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj}
18944
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5105 Set the profiler function to \var{func}. The \var{obj} parameter is
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5106 passed to the function as its first parameter, and may be any Python
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5107 object, or \NULL. If the profile function needs to maintain state,
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5108 using a different value for \var{obj} for each thread provides a
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5109 convenient and thread-safe place to store it. The profile function
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5110 is called for all monitored events except the line-number events.
18671
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5111 \end{cfuncdesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5112
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5113 \begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj}
18944
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5114 Set the the tracing function to \var{func}. This is similar to
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5115 \cfunction{PyEval_SetProfile()}, except the tracing function does
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5116 receive line-number events.
18671
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5117 \end{cfuncdesc}
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5118
38206f29b0fc Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents: 18576
diff changeset
5119
19076
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5120 \section{Advanced Debugger Support \label{advanced-debugging}}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5121 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5122
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5123 These functions are only intended to be used by advanced debugging
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5124 tools.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5125
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5126 \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5127 Return the interpreter state object at the head of the list of all
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5128 such objects.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5129 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5130 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5131
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5132 \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5133 Return the next interpreter state object after \var{interp} from the
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5134 list of all such objects.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5135 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5136 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5137
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5138 \begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5139 Return the a pointer to the first \ctype{PyThreadState} object in the
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5140 list of threads associated with the interpreter \var{interp}.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5141 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5142 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5143
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5144 \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5145 Return the next thread state object after \var{tstate} from the list
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5146 of all such objects belonging to the same \ctype{PyInterpreterState}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5147 object.
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5148 \versionadded{2.2}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5149 \end{cfuncdesc}
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5150
f75125ead0a2 Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents: 18944
diff changeset
5151
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5152 \chapter{Memory Management \label{memory}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5153 \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
5154
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 \section{Overview \label{memoryOverview}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5157
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5158 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
5159 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
5160 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
5161 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
5162 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
5163 preallocation or caching.
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 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
5166 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
5167 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
5168 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
5169 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
5170 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
5171 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
5172 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
5173 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
5174 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
5175 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
5176 the private heap.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5177
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5178 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
5179 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
5180 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
5181 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
5182 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
5183 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
5184 this document.
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 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
5187 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
5188 library: \cfunction{malloc()}\ttindex{malloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5189 \cfunction{calloc()}\ttindex{calloc()},
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5190 \cfunction{realloc()}\ttindex{realloc()} and
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5191 \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
5192 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
5193 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
5194 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
5195 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
5196 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
5197
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5198 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5199 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5200 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
5201
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5202 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5203 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5204 ...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
5205 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5206 free(buf); /* malloc'ed */
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5207 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5208 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5209
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5210 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
5211 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
5212 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
5213
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5214 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
5215 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
5216 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
5217 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
5218 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
5219 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
5220 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
5221 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
5222 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
5223 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
5224 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
5225 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
5226 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
5227 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
5228 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
5229
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5230
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5231 \section{Memory Interface \label{memoryInterface}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5232
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5233 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
5234 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
5235
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5236
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
5237 \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
5238 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
5239 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
5240 bytes returns a non-\NULL{} pointer.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5241 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
5242 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5243
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
5244 \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
5245 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
5246 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
5247 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
5248 \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
5249 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
5250 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
5251 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
5252 \cfunction{PyMem_Realloc()}.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5253 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5254
13920
d057cd543ed9 ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents: 13592
diff changeset
5255 \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
5256 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
5257 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
5258 \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
5259 \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
5260 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
5261 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5262
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5263 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
5264 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
5265
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5266 \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
5267 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
5268 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
5269 \ctype{\var{TYPE}*}.
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5270 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
5271 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5272
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5273 \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
5274 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
5275 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
5276 cast to \ctype{\var{TYPE}*}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5277 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5278
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5279 \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
5280 Same as \cfunction{PyMem_Free()}.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5281 \end{cfuncdesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5282
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5283 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
5284 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
5285 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
5286 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
5287 extension modules.
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5288
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5289 \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
5290
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5291 \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
5292
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5293
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5294 \section{Examples \label{memoryExamples}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5295
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5296 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
5297 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
5298 first function set:
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5299
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5300 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5301 PyObject *res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5302 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
5303
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5304 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5305 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5306 /* ...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
5307 res = PyString_FromString(buf);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5308 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
5309 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5310 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5311
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5312 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
5313
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5314 \begin{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5315 PyObject *res;
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5316 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
5317
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5318 if (buf == NULL)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5319 return PyErr_NoMemory();
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5320 /* ...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
5321 res = PyString_FromString(buf);
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5322 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
5323 return res;
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5324 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5325
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5326 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
5327 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
5328 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
5329 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
5330 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
5331 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
5332 allocators operating on different heaps.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5333
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5334 \begin{verbatim}
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5335 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
5336 char *buf2 = (char *) malloc(BUFSIZ);
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5337 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
5338 ...
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5339 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
5340 free(buf2); /* Right -- allocated via malloc() */
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5341 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
5342 \end{verbatim}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5343
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5344 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
5345 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
5346 \cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5347 \cfunction{PyObject_Del()}, or with their corresponding macros
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5348 \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
5349 \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
5350
e2aee6190b19 Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents: 13150
diff changeset
5351 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
5352 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
5353
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5354
10163
ddf861d84bbb Markup nits.
Fred Drake <fdrake@acm.org>
parents: 9931
diff changeset
5355 \chapter{Defining New Object Types \label{newTypes}}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
5356
18785
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
5357
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
5358 \section{Allocating Objects on the Heap
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
5359 \label{allocating-objects}}
b465cd50cf36 Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents: 18671
diff changeset
5360
7782
7fc32a66255a Markup consistency & nits.
Fred Drake <fdrake@acm.org>
parents: 7708
diff changeset
5361 \begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type}
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
5362 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
5363
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5364 \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
5365 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5366
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5367 \begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5368 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5369
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5370 \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
5371 PyTypeObject *type}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5372 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
5373 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
5374 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
5375 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
5376 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
5377 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5378
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5379 \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
5380 PyTypeObject *type, int size}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5381 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
5382 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
5383 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5384
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5385 \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
5386 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
5387 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
5388 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
5389 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
5390 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
5391 type object.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5392 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5393
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5394 \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
5395 int size}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5396 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
5397 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
5398 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
5399 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
5400 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
5401 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
5402 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
5403 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
5404 improving the memory management efficiency.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5405 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5406
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5407 \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
5408 Releases memory allocated to an object using
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5409 \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
5410 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
5411 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
5412 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
5413 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5414
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5415 \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
5416 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
5417 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
5418 value.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5419 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5420
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5421 \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
5422 int size}
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5423 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
5424 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
5425 \NULL{} value.
14526
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5426 \end{cfuncdesc}
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5427
ff4ae691be9b Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents: 14519
diff changeset
5428 \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
5429 Macro version of \cfunction{PyObject_Del()}.
7308
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
5430 \end{cfuncdesc}
8096fec722ba Lots of nitty-gritty stuff:
Fred Drake <fdrake@acm.org>
parents: 7278
diff changeset
5431
15444
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5432 \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
5433 PyMethodDef *methods}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5434 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
5435 returning the new module object.
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5436 \end{cfuncdesc}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5437
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5438 \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
5439 PyMethodDef *methods,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5440 char *doc}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5441 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
5442 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
5443 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
5444 \end{cfuncdesc}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5445
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5446 \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
5447 PyMethodDef *methods,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5448 char *doc, PyObject *self,
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5449 int apiver}
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5450 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
5451 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
5452 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
5453 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
5454 (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
5455 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
5456 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
5457 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
5458
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5459 \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
5460 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
5461 sure you need it.
7e514f1fe31f Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents: 15300
diff changeset
5462 \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
5463
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5464 DL_IMPORT
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5465
18447
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5466 \begin{cvardesc}{PyObject}{_Py_NoneStruct}
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5467 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
5468 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
5469 pointer to this object.
ca2ea75df3f2 Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents: 18438
diff changeset
5470 \end{cvardesc}
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5471
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5472
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5473 \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
5474
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5475 PyObject, PyVarObject
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5476
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5477 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
5478
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5479 Typedefs:
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5480 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
5481 intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5482 destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5483 setattrofunc, cmpfunc, reprfunc, hashfunc
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
5484
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5485 \begin{ctypedesc}{PyCFunction}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5486 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
5487 \end{ctypedesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5488
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5489 \begin{ctypedesc}{PyMethodDef}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5490 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
5491 structure has four fields:
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5492
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5493 \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
5494 \lineiii{ml_name}{char *}{name of the method}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5495 \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
5496 \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
5497 constructed}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5498 \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
5499 \end{tableiii}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5500 \end{ctypedesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5501
19301
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5502 The \var{ml_meth} is a C function pointer. The functions may be of
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5503 different types, but they always return \ctype{PyObject*}. If the
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5504 function is not of the \ctype{PyCFunction}, the compiler will require
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5505 a cast in the method table. Even though \ctype{PyCFunction} defines
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5506 the first parameter as \ctype{PyObject*}, it is common that the method
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5507 implementation uses a the specific C type of the \var{self} object.
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5508
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5509 The flags can have the following values. Only METH_VARARGS and
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5510 METH_KEYWORDS can be combined; the others can't.
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5511
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5512 \begin{datadesc}{METH_VARARGS}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5513
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5514 This is the typical calling convention, where the methods have the
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5515 type \ctype{PyMethodDef}. The function expects two \ctype{PyObject*}.
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5516 The first one is the \var{self} object for methods; for module
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5517 functions, it has the value given to \cfunction{PyInitModule4} (or
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5518 \NULL{} if \cfunction{PyInitModule} was used). The second parameter
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5519 (often called \var{args}) is a tuple object representing all
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5520 arguments. This parameter is typically processed using
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5521 \cfunction{PyArg_ParseTuple}.
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5522
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5523 \end{datadesc}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5524
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5525 \begin{datadesc}{METH_KEYWORDS}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5526
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5527 Methods with these flags must be of type
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5528 \ctype{PyCFunctionWithKeywords}. The function expects three
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5529 parameters: \var{self}, \var{args}, and a dictionary of all the keyword
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5530 arguments. The flag is typically combined with METH_VARARGS, and the
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5531 parameters are typically processed using
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5532 \cfunction{PyArg_ParseTupleAndKeywords}.
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5533
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5534 \end{datadesc}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5535
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5536 \begin{datadesc}{METH_NOARGS}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5537
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5538 Methods without parameters don't need to check whether arguments are
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5539 given if they are listed with the \code{METH_NOARGS} flag. They need
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5540 to be of type \ctype{PyNoArgsFunction}, i.e. they expect a single
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5541 \var{self} parameter.
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5542
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5543 \end{datadesc}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5544
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5545 \begin{datadesc}{METH_O}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5546
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5547 Methods with a single object argument can be listed with the
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5548 \code{METH_O} flag, instead of invoking \cfunction{PyArg_ParseTuple}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5549 with a \code{``O''} argument. They have the type \ctype{PyCFunction},
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5550 with the \var{self} parameter, and a \ctype{PyObject*} parameter
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5551 representing the single argument.
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5552
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5553 \end{datadesc}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5554
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5555 \begin{datadesc}{METH_OLDARGS}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5556
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5557 This calling convention is deprecated. The method must be of type
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5558 \ctype{PyCFunction}. The second argument is \NULL{} if no arguments
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5559 are given, a single object if exactly one argument is given, and a
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5560 tuple of objects if more than one argument is given.
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5561
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5562 \end{datadesc}
b9701538f827 Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents: 19242
diff changeset
5563
12930
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5564 \begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef[] table,
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5565 PyObject *ob, char *name}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5566 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
5567 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
5568 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
5569 \end{cfuncdesc}
6618325574cb Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents: 12355
diff changeset
5570
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5571
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5572 \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
5573
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5574 \begin{ctypedesc}{PyMappingMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5575 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
5576 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
5577 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5578
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5579
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5580 \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
5581
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5582 \begin{ctypedesc}{PyNumberMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5583 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
5584 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
5585 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5586
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5587
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5588 \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
5589
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5590 \begin{ctypedesc}{PySequenceMethods}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5591 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
5592 to implement the sequence protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5593 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5594
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5595
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5596 \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
5597 \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
5598
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5599 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
5600 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
5601 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
5602 \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
5603
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5604 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
5605 \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
5606 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
5607 a \ctype{PyBufferProcs} structure.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5608
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5609 \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
5610 \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
5611 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
5612 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
5613 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
5614 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
5615 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
5616
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5617 \begin{ctypedesc}{PyBufferProcs}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5618 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
5619 implementation of the buffer protocol.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5620
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5621 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
5622 \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
5623 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
5624 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
5625 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
5626
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5627 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
5628 \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
5629 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
5630
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5631 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
5632 \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
5633 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
5634 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
5635 \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
5636
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5637 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
5638 \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
5639 \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
5640 \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
5641 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
5642 \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
5643 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
5644 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
5645 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
5646 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
5647 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
5648 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
5649 \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
5650 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
5651 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
5652 have character-based content.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5653
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5654 \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
5655 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
5656 \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
5657 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5658
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5659 \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
5660 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
5661 \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
5662 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
5663 \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
5664 \end{datadesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5665
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5666 \begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5667 (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
5668 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
5669 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
5670 \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
5671 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
5672 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
5673 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
5674 pointer to that memory.
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5675 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5676
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5677 \begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5678 (PyObject *self, int segment, void **ptrptr)}
17336
2146a73ce35c Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents: 17307
diff changeset
5679 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
5680 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
5681 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
5682 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
5683 \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
5684 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
5685 \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
5686 % 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
5687 % 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
5688 % 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
5689 % code.
11176
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
5690 \end{ctypedesc}
64b15e9091a9 Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents: 11168
diff changeset
5691
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5692 \begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5693 (PyObject *self, int *lenp)}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5694 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
5695 \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
5696 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
5697 The function cannot fail.
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5698 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5699
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5700 \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc)
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5701 (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
5702 \end{ctypedesc}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5703
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5704
18944
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5705 \section{Supporting the Iterator Protocol
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5706 \label{supporting-iteration}}
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5707
a0819708fe9c Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents: 18785
diff changeset
5708
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5709 \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
5710 \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
5711
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5712 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
5713 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
5714 ``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
5715 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
5716 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
5717 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
5718
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5719 To create a container type, the \member{tp_flags} field of the type
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5720 object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5721 implementation of the \member{tp_traverse} handler. If instances of the
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5722 type are mutable, a \member{tp_clear} implementation must also be
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5723 provided.
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5724
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5725 \begin{datadesc}{Py_TPFLAGS_HAVE_GC}
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5726 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
5727 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
5728 as container objects.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5729 \end{datadesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5730
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
5731 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
5732
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5733 \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
5734 \item The memory for the object must be allocated using
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5735 \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}.
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
5736
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5737 \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
5738 containers are initialized, it must call
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5739 \cfunction{PyObject_GC_Track()}.
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
5740 \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
5741
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5742 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_New}{TYPE, PyTypeObject *type}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5743 Analogous to \cfunction{PyObject_New()} but for container objects with
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5744 the \constant{Py_TPFLAGS_HAVE_GC} flag set.
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5745 \end{cfuncdesc}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5746
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5747 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type,
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5748 int size}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5749 Analogous to \cfunction{PyObject_NewVar()} but for container objects
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5750 with the \constant{Py_TPFLAGS_HAVE_GC} flag set.
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5751 \end{cfuncdesc}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5752
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5753 \begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, int}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5754 Resize an object allocated by \cfunction{PyObject_NewVar()}. Returns
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5755 the resized object or \NULL{} on failure.
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5756 \end{cfuncdesc}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5757
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5758 \begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op}
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5759 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
5760 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
5761 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
5762 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
5763 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
5764 \end{cfuncdesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5765
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5766 \begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5767 A macro version of \cfunction{PyObject_GC_Track()}. It should not be
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5768 used for extension modules.
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5769 \end{cfuncdesc}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5770
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
5771 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
5772 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
5773
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5774 \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
5775 \item Before fields which refer to other containers are invalidated,
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5776 \cfunction{PyObject_GC_UnTrack()} must be called.
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
5777
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5778 \item The object's memory must be deallocated using
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5779 \cfunction{PyObject_GC_Del()}.
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
5780 \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
5781
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5782 \begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5783 Releases memory allocated to an object using
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5784 \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}.
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5785 \end{cfuncdesc}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5786
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5787 \begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op}
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5788 Remove the object \var{op} from the set of container objects tracked
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5789 by the collector. Note that \cfunction{PyObject_GC_Track()} can be
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5790 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
5791 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
5792 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
5793 \member{tp_traverse} handler become invalid.
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5794 \end{cfuncdesc}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5795
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5796 \begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op}
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5797 A macro version of \cfunction{PyObject_GC_UnTrack()}. It should not be
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5798 used for extension modules.
17118
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5799 \end{cfuncdesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5800
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5801 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
5802 type:
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5803
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5804 \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
5805 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
5806 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
5807 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
5808 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
5809 \end{ctypedesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5810
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5811 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
5812
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5813 \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
5814 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
5815 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
5816 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
5817 \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
5818 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
5819 \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
5820 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
5821 \end{ctypedesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5822
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5823 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
5824 \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
5825
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5826 \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
5827 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
5828 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
5829 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
5830 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
5831 \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
5832 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
5833 reference cycle.
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5834 \end{ctypedesc}
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5835
f9a07e99907e Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents: 17057
diff changeset
5836
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
5837 \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
5838 \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
5839
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5840 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
5841 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
5842 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
5843 \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
5844 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
5845 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
5846 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
5847 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
5848 \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
5849 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
5850 \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
5851
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5852 \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
5853 #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
5854
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5855 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
5856 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
5857 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
5858 } 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
5859
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5860 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
5861 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
5862 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5863 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
5864 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
5865 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
5866 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
5867 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5868
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5869 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
5870 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
5871 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5872 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
5873 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
5874
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5875 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
5876 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5877
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5878 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
5879 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
5880 {
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5881 PyObject_GC_UnTrack((PyObject *) self);
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
5882 Py_XDECREF(self->container);
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5883 PyObject_GC_Del(self);
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
5884 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5885 \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
5886
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5887 \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
5888 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
5889 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
5890 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
5891 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
5892 "MyObject",
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5893 sizeof(MyObject),
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
5894 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
5895 (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
5896 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
5897 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
5898 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
5899 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
5900 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
5901 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
5902 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
5903 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
5904 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
5905 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
5906 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
5907 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
5908 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
5909 0, /* tp_as_buffer */
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5910 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC,
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
5911 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
5912 (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
5913 (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
5914 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
5915 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
5916 };
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5917
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5918 /* 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
5919 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
5920 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
5921 {
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5922 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
5923 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
5924
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5925 if (PyArg_ParseTuple(args, "|O:new_object", &container)) {
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5926 result = PyObject_GC_New(MyObject, &MyObject_Type);
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
5927 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
5928 result->container = container;
19607
43fe9377e2cf Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents: 19524
diff changeset
5929 PyObject_GC_Track(result);
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
5930 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5931 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5932 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
5933 }
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5934 \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
5935
349c8788604e Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents: 17118
diff changeset
5936
12222
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5937 % \chapter{Debugging \label{debugging}}
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5938 %
3e9a1c1a9f56 Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents: 12200
diff changeset
5939 % 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
5940
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
5941
14736
2b9a890162b0 Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents: 14696
diff changeset
5942 \appendix
2b9a890162b0 Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents: 14696
diff changeset
5943 \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
5944 \input{reportingbugs}
2b9a890162b0 Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents: 14696
diff changeset
5945
18192
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
5946 \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
5947 \input{license}
19bc63a84439 Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents: 18020
diff changeset
5948
15953
8349b4dfc51a Undoing the whitespace patches which sneaked into the earlier patch.
Marc-André Lemburg <mal@egenix.com>
parents: 15952
diff changeset
5949 \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
5950
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
5951 \end{document}