Mercurial > cpython-lru_cache-weakref

annotate Doc/api/api.tex @ 6719:faebc1940432 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Understand -Xlinker option.
author Guido van Rossum <guido@python.org>
date Tue, 02 Dec 1997 20:38:11 +0000
parents c6c1d133677a
children f349bf0e9322
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1 \documentstyle[twoside,11pt,myformat]{report}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
3 \title{Python/C API Reference Manual}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
4
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
5 \input{boilerplate}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
6
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
7 \makeindex % tell \index to actually write the .idx file
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
8
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
9
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
10 \begin{document}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
11
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
12 \pagenumbering{roman}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
13
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
14 \maketitle
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
15
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
16 \input{copyright}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
17
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
18 \begin{abstract}
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 \noindent
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 This manual documents the API used by C (or C++) programmers who want
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
22 to write extension modules or embed Python. It is a companion to
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
23 ``Extending and Embedding the Python Interpreter'', which describes
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
24 the general principles of extension writing but does not document the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
25 API functions in detail.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
26
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
27 \end{abstract}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
28
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
29 \pagebreak
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
30
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 {
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
32 \parskip = 0mm
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
33 \tableofcontents
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
34 }
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
35
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
36 \pagebreak
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
37
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 \pagenumbering{arabic}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
39
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
40 % 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
41 % 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
42
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
43 \chapter{Introduction}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
44
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
45 The Application Programmer's Interface to Python gives C and C++
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
46 programmers access to the Python interpreter at a variety of levels.
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
47 The API is equally usable from C++, but for brevity it is generally
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
48 referred to as the Python/C API. There are two fundamentally
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
49 different reasons for using the Python/C API. The first reason is to
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
50 write ``extension modules'' for specific purposes; these are C modules
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
51 that extend the Python interpreter. This is probably the most common
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
52 use. The second reason is to use Python as a component in a larger
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
53 application; this technique is generally referred to as ``embedding''
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
54 Python in an application.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
55
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
56 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
57 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
58 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
59 Python in other applications since its early existence, the process of
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
60 embedding Python is less straightforward that writing an extension.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
61 Python 1.5 introduces a number of new API functions as well as some
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
62 changes to the build process that make embedding much simpler.
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
63 This manual describes the 1.5 state of affair.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
64 % XXX Eventually, take the historical notes out
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
65
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
66 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
67 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
68 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
69 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
70 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
71
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
72 \section{Include Files}
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
73
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
74 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
75 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
76
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
77 \code{\#include "Python.h"}
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
78
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
79 This implies inclusion of the following standard header files:
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
80 stdio.h, string.h, errno.h, and stdlib.h (if available).
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
81
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 All user visible names defined by Python.h (except those defined by
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 the included standard headers) have one of the prefixes \code{Py} or
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
84 \code{_Py}. Names beginning with \code{_Py} are for internal use
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
85 only. Structure member names do not have a reserved prefix.
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
86
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
87 Important: user code should never define names that begin with
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 \code{Py} or \code{_Py}. This confuses the reader, and jeopardizes
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
89 the portability of the user code to future Python versions, which may
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
90 define additional names beginning with one of these prefixes.
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
91
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
92 \section{Objects, Types and Reference Counts}
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
93
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 Most Python/C API functions have one or more arguments as well as a
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
95 return value of type \code{PyObject *}. This type is a pointer
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
96 (obviously!) to an opaque data type representing an arbitrary 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
97 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
98 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
99 and argument passing), it is only fitting that they should be
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
100 represented by a single C type. All Python objects live on the heap:
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
101 you never declare an automatic or static variable of type
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
102 \code{PyObject}, only pointer variables of type \code{PyObject *} can
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
103 be declared.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
104
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
105 All Python objects (even Python integers) have a ``type'' and a
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
106 ``reference count''. An object's type determines what kind of object
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
107 it is (e.g., an integer, a list, or a user-defined function; there are
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
108 many more as explained in the Python Language Reference Manual). For
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
109 each of the well-known types there is a macro to check whether an
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
110 object is of that type; for instance, \code{PyList_Check(a)} is true
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
111 iff the object pointed to by \code{a} is a Python list.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
112
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
113 \subsection{Reference Counts}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
114
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
115 The reference count is important because today's computers have a
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
116 finite (and often severly limited) memory size; it counts how many
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
117 different places there are that have a reference to an object. Such a
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
118 place could be another object, or a global (or static) C variable, or
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
119 a local variable in some C function. When an object's reference count
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
120 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
121 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
122 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
123 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
124 with objects that reference each other here; for now, the solution is
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
125 ``don't do that''.)
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
126
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
127 Reference counts are always manipulated explicitly. The normal way is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
128 to use the macro \code{Py_INCREF(a)} to increment an object's
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
129 reference count by one, and \code{Py_DECREF(a)} to decrement it by
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
130 one. The decref macro is considerably more complex than the incref one,
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
131 since it must check whether the reference count becomes zero and then
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
132 cause the object's deallocator, which is a function pointer contained
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
133 in the object's type structure. The type-specific deallocator takes
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
134 care of decrementing the reference counts for other objects contained
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
135 in the object, and so on, if this is a compound object type such as a
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
136 list. There's no chance that the reference count can overflow; at
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
137 least as many bits are used to hold the reference count as there are
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
138 distinct memory locations in virtual memory (assuming
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
139 \code{sizeof(long) >= sizeof(char *)}). Thus, the reference count
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
140 increment is a simple operation.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
141
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
142 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
143 local variable that contains a pointer to an object. In theory, the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
144 oject's reference count goes up by one when the variable is made to
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
145 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
146 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
147 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
148 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
149 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
150 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
151 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
152 temporarily. An important situation where this arises is in objects
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
153 that are passed as arguments to C functions in an extension module
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
154 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
155 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
156
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
157 However, a common pitfall is to extract an object from a list and
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
158 holding on to it for a while without incrementing its reference count.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
159 Some other operation might conceivably remove the object from the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
160 list, decrementing its reference count and possible deallocating it.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
161 The real danger is that innocent-looking operations may invoke
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
162 arbitrary Python code which could do this; there is a code path which
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
163 allows control to flow back to the user from a \code{Py_DECREF()}, so
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
164 almost any operation is potentially dangerous.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
165
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
166 A safe approach is to always use the generic operations (functions
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
167 whose name begins with \code{PyObject_}, \code{PyNumber_},
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
168 \code{PySequence_} or \code{PyMapping_}). These operations always
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
169 increment the reference count of the object they return. This leaves
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
170 the caller with the responsibility to call \code{Py_DECREF()} when
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
171 they are done with the result; this soon becomes second nature.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
172
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
173 \subsubsection{Reference Count Details}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
174
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
175 The reference count behavior of functions in the Python/C API is best
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
176 expelained 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
177 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
178 shared! When a function owns a reference, it has to dispose of it
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
179 properly -- either by passing ownership on (usually to its caller) or
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
180 by calling \code{Py_DECREF()} or \code{Py_XDECREF()}. When a 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
181 passes ownership of a reference on to its caller, the caller is said
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
182 to receive a \emph{new} reference. When to ownership is transferred,
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
183 the caller is said to \emph{borrow} the reference. Nothing needs 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
184 be done for a borrowed 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
185
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
186 Conversely, when calling a function passes it a reference to an
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
187 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
188 reference to the object, or it does not. Few functions steal
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
189 references; the two notable exceptions are \code{PyList_SetItem()} and
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
190 \code{PyTuple_SetItem()}, which steal a reference to the item (but not to
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
191 the tuple or list into which the item it put!). These functions were
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
192 designed to steal a reference because of a common idiom for populating
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
193 a tuple or list with newly created objects; for example, the code to
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
194 create the tuple \code{(1, 2, "three")} could look like this
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
195 (forgetting about error handling for the moment; a better way to code
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
196 this is shown below anyway):
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
197
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
198 \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
199 PyObject *t;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
200 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
201 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
202 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
203 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
204 \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
205
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
206 Incidentally, \code{PyTuple_SetItem()} is the \emph{only} way to set
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
207 tuple items; \code{PyObject_SetItem()} refuses to do this since tuples
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
208 are an immutable data type. You should only use
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 \code{PyTuple_SetItem()} for tuples that you are creating yourself.
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
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
211 Equivalent code for populating a list can be written using
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
212 \code{PyList_New()} and \code{PyList_SetItem()}. Such code can also
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 use \code{PySequence_SetItem()}; this illustrates the difference
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
214 between the two:
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
215
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
216 \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
217 PyObject *l, *x;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
218 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
219 x = 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
220 PyObject_SetItem(l, 0, x); Py_DECREF(x);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
221 x = 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
222 PyObject_SetItem(l, 1, x); Py_DECREF(x);
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 x = 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
224 PyObject_SetItem(l, 2, x); Py_DECREF(x);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
225 \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
226
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
227 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
228 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
229 creating and populating a tuple or list. There's a generic function,
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
230 \code{Py_BuildValue()}, that can create most common objects from C
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
231 values, directed by a ``format string''. For example, the above two
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
232 blocks of code could be replaced by the following (which also takes
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 care of the error checking!):
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
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 \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
236 PyObject *t, *l;
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 = 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
238 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
239 \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
240
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 It is much more common to use \code{PyObject_SetItem()} and friends
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 with items whose references you are only borrowing, like arguments
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
243 that were passed in to the function you are writing. In that case,
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
244 their behaviour regarding reference counts is much saner, since you
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
245 don't have to increment a reference count so you can give a 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
246 away (``have it be stolen''). For example, this function sets all
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
247 items of a list (actually, any mutable sequence) to a given 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
248
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 \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
250 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
251 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
252 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
253 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
254 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
255 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
256 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
257 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
258 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
259 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
260 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
261 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
262 \end{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
263
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
264 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
265 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
266 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
267 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
268 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
269 on the fly, and the reference you get is the only reference to 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
270 object! Therefore, the generic functions that return object
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
271 references, like \code{PyObject_GetItem()} and
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
272 \code{PySequence_GetItem()}, always return a new reference (i.e., 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
273 caller becomes the owner 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
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 It is important to realize that whether you own a reference returned
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 by a function depends on which function you call only -- \emph{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
277 plumage} (i.e., the type of the type of the object passed as 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
278 argument to the function) \emph{don't enter into it!} Thus, if you
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 extract an item from a list using \code{PyList_GetItem()}, yo don't
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 own the reference -- but if you obtain the same item from the same
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 list using \code{PySequence_GetItem()} (which happens to take exactly
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
282 the same arguments), you do own a reference to the returned object.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
283
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
284 Here is an example of how you could write a function that computes 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
285 sum of the items in a list of integers; once using
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
286 \code{PyList_GetItem()}, once using \code{PySequence_GetItem()}.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
287
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
288 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
289 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
290 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
291 int i, n;
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 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
293 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
294 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
295 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
296 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
297 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
298 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
299 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
300 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
301 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
302 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
303 }
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 \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
305
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
306 \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
307 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
308 {
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 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
310 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
311 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
312 n = PyObject_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
313 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
314 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
315 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
316 item = PySequence_GetItem(list, 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
317 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
318 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
319 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
320 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
321 Py_DECREF(item); /* Discared reference ownership */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
322 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
323 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
324 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
325 \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
326
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
327 \subsection{Types}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
328
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
329 There are few other data types that play a significant role in
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
330 the Python/C API; most are simple C types such as \code{int},
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
331 \code{long}, \code{double} and \code{char *}. A few structure types
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
332 are used to describe static tables used to list the functions exported
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
333 by a module or the data attributes of a new object type. These will
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
334 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
335
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
336 \section{Exceptions}
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
337
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
338 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
339 error handling is required; unhandled exceptions are automatically
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
340 propagated to the caller, then to the caller's caller, and so on, till
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
341 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
342 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
343
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 C programmers, however, error checking always has to be explicit.
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 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
346 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
347 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
348 discards any object references that it owns, and returns an
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
349 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
350 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
351 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
352 ambiguous return value, and require explicit testing for errors with
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 \code{PyErr_Occurred()}.
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
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 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
356 equivalent to using global storage in an unthreaded application). 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
357 thread can be on one of two states: an exception has occurred, or not.
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 The function \code{PyErr_Occurred()} can be used to check for this: it
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 returns a borrowed reference to the exception type object when an
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
360 exception has occurred, and \NULL{} otherwise. There are a number
6084
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 of functions to set the exception state: \code{PyErr_SetString()} 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
362 the most common (though not the most general) function to set 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
363 exception state, and \code{PyErr_Clear()} clears the exception state.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
364
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
365 The full exception state consists of three objects (all of which can
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
366 be \NULL{} ): the exception type, the corresponding exception
6084
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 value, and the traceback. These have the same meanings as the Python
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 object \code{sys.exc_type}, \code{sys.exc_value},
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
369 \code{sys.exc_traceback}; however, they are not the same: the Python
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 objects represent the last exception being handled by a Python
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 \code{try...except} statement, while the C level exception state only
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 exists while an exception is being passed on between C functions until
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 it reaches the Python interpreter, which takes care of transferring it
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
374 to \code{sys.exc_type} and friends.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
375
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
376 (Note that starting with Python 1.5, the preferred, thread-safe way 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
377 access the exception state from Python code is to call the 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
378 \code{sys.exc_info()}, which returns the per-thread exception state
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 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
380 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
381 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
382 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
383 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
384 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
385 unwanted lifetime extension for objects that are referenced by 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
386 stack frames in the traceback.)
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
387
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
388 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
389 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
390 exception, and if so, pass the exception state on to its caller. It
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
391 should discards any object references that it owns, and returns 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
392 error indicator, but it should \emph{not} set another 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
393 that would overwrite the exception that was just raised, and lose
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 important reason about the exact cause of the error.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
395
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
396 A simple example of detecting exceptions and passing them on is shown
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 in the \code{sum_sequence()} example above. It so happens that 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
398 example doesn't need to clean up any owned references when it detects
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 an error. The following example function shows some error cleanup.
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
400 First, to remind you why you like Python, we show the equivalent
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
401 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
402
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 \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
404 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
405 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
406 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
407 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
408 item = 0
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
409 return item + 1
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
410 \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
411
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
412 Here is the corresponding C code, in all its glory:
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
413
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
414 \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
415 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
416 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
417 /* 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
418 PyObject *item = NULL, *const_one = NULL, *incremented_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
419 int rv = -1; /* Return value initialized to -1 (faulure) */
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
420
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
421 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
422 if (item == NULL) {
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
423 /* Handle keyError only: */
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
424 if (!PyErr_ExceptionMatches(PyExc_keyError)) goto error;
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
425
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 /* 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
427 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
428 item = PyInt_FromLong(0L);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
429 if (item == NULL) goto error;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
430 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
431
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 const_one = PyInt_FromLong(1L);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
433 if (const_one == NULL) goto error;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
434
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
435 incremented_item = PyNumber_Add(item, const_one);
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
436 if (incremented_item == NULL) goto error;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
437
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
438 if (PyObject_SetItem(dict, key, incremented_item) < 0) goto error;
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
439 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
440 /* 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
441
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 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
443 /* 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
444
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 /* 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
446 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
447 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
448 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
449
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
450 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
451 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
452 \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
453
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
454 This example represents an endorsed use of the \code{goto} statement
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
455 in C! It illustrates the use of \code{PyErr_ExceptionMatches()} and
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
456 \code{PyErr_Clear()} to handle specific exceptions, and the use of
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
457 \code{Py_XDECREF()} to dispose of owned references that 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
458 \NULL{} (note the `X' in the name; \code{Py_DECREF()} would crash
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
459 when confronted with a \NULL{} reference). It is important that
6084
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 the variables used to hold owned references are initialized to
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
461 \NULL{} for this to work; likewise, the proposed return value is
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 initialized to \code{-1} (failure) and only set to success after
6084
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 the final call made is succesful.
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
464
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
465
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
466 \section{Embedding Python}
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
467
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
468 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
469 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
470 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
471 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
472 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
473
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
474 The basic initialization function is \code{Py_Initialize()}. This
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
475 initializes the table of loaded modules, and creates the fundamental
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
476 modules \code{__builtin__}, \code{__main__} and \code{sys}. It also
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
477 initializes the module search path (\code{sys.path}).
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
478
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
479 \code{Py_Initialize()} does not set the ``script argument list''
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
480 (\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
481 will be executed later, it must be set explicitly with a call to
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
482 \code{PySys_SetArgv(\var{argc}, \var{argv})} subsequent to the call
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
483 to \code{Py_Initialize()}.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
484
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
485 On most systems (in particular, on Unix and Windows, although the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
486 details are slightly different), \code{Py_Initialize()} calculates the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
487 module search path based upon its best guess for the location of the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
488 standard Python interpreter executable, assuming that the Python
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
489 library is found in a fixed location relative to the Python
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
490 interpreter executable. In particular, it looks for a directory named
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
491 \code{lib/python1.5} (replacing \code{1.5} with the current
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
492 interpreter version) relative to the parent directory where the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
493 executable named \code{python} is found on the shell command search
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
494 path (the environment variable \code{\$PATH}).
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
495
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
496 For instance, if the Python executable is found in
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
497 \code{/usr/local/bin/python}, it will assume that the libraries are in
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
498 \code{/usr/local/lib/python1.5}. (In fact, this particular path is
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
499 also the ``fallback'' location, used when no executable file named
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
500 \code{python} is found along \code{\$PATH}.) The user can override
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
501 this behavior by setting the environment variable \code{\$PYTHONHOME},
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
502 or insert additional directories in front of the standard path by
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
503 setting \code{\$PYTHONPATH}.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
504
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
505 The embedding application can steer the search by calling
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
506 \code{Py_SetProgramName(\var{file})} \emph{before} calling
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
507 \code{Py_Initialize()}. Note that \code{\$PYTHONHOME} still overrides
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
508 this and \code{\$PYTHONPATH} is still inserted in front of 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
509 standard path. An application that requires total control has to
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
510 provide its own implementation of \code{Py_GetPath()},
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
511 \code{Py_GetPrefix()}, \code{Py_GetExecPrefix()},
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
512 \code{Py_GetProgramFullPath()} (all defined in
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
513 \file{Modules/getpath.c}).
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
514
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
515 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
516 the application may want to start over (make another call to
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
517 \code{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
518 use of Python and wants to free all memory allocated by Python. This
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
519 can be accomplished by calling \code{Py_Finalize()}. The function
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
520 \code{Py_IsInitialized()} returns true iff Python is currently in 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
521 initialized state. More information about these functions is given in
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
522 a later chapter.
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
523
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
524
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
525 \chapter{Basic Utilities}
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
526
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
527 XXX These utilities should be moved to some other section...
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
528
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
529 \begin{cfuncdesc}{void}{Py_FatalError}{char *message}
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
530 Print a fatal error message and kill the process. No cleanup is
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
531 performed. This function should only be invoked when a condition is
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
532 detected that would make it dangerous to continue using 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
533 interpreter; e.g., when the object administration appears to be
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
534 corrupted. On Unix, the standard C library function \code{abort()} is
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 called which will attempt to produce a \file{core} file.
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 \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
537
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 \begin{cfuncdesc}{void}{Py_Exit}{int status}
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 Exit the current process. This calls \code{Py_Finalize()} and then
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
540 calls the standard C library function \code{exit(0)}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
541 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
542
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
543 \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
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
544 Register a cleanup function to be called by \code{Py_Finalize()}. The
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
545 cleanup function will be called with no arguments and should return no
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
546 value. At most 32 cleanup functions can be registered. When the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
547 registration is successful, \code{Py_AtExit} returns 0; on failure, it
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
548 returns -1. The cleanup function registered last is called first.
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
549 Each cleanup function will be called at most once.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
550 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
551
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
552
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
553 \chapter{Reference Counting}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
554
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
555 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
556 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
557
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
558 \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
559 Increment the reference count for object \code{o}. The object must
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
560 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
561 \code{Py_XINCREF()}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
562 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
563
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
564 \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
565 Increment the reference count for object \code{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
566 \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
567 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
568
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
569 \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
570 Decrement the reference count for object \code{o}. The object must
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
571 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
572 \code{Py_XDECREF()}. If the reference count reaches zero, the object's
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
573 type's deallocation function (which must not be \NULL{}) is invoked.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
574
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
575 \strong{Warning:} The deallocation function can cause arbitrary Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
576 code to be invoked (e.g. when a class instance with a \code{__del__()}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
577 method is deallocated). While exceptions in such code are not
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
578 propagated, the executed code has free access to all Python global
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
579 variables. This means that any object that is reachable from a global
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
580 variable should be in a consistent state before \code{Py_DECREF()} is
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
581 invoked. For example, code to delete an object from a list should
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
582 copy a reference to the deleted object in a temporary variable, update
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
583 the list data structure, and then call \code{Py_DECREF()} for the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
584 temporary variable.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
585 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
586
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
587 \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
588 Decrement the reference count for object \code{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
589 \NULL{}, in which case the macro has no effect; otherwise the
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
590 effect is the same as for \code{Py_DECREF()}, and the same warning
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
591 applies.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
592 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
593
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
594 The following functions or macros are only for internal use:
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
595 \code{_Py_Dealloc}, \code{_Py_ForgetReference}, \code{_Py_NewReference},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
596 as well as the global variable \code{_Py_RefTotal}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
597
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 XXX Should mention Py_Malloc(), Py_Realloc(), Py_Free(),
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 PyMem_Malloc(), PyMem_Realloc(), PyMem_Free(), PyMem_NEW(),
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
600 PyMem_RESIZE(), PyMem_DEL(), PyMem_XDEL().
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
601
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
602
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
603 \chapter{Exception Handling}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
604
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
605 The functions 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
606 exceptions. It is important to understand some of the basics of
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
607 Python exception handling. It works somewhat like the Unix
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
608 \code{errno} variable: there is a global indicator (per thread) of the
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
609 last error that occurred. Most functions don't clear this on success,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
610 but will set it to indicate the cause of the error on failure. Most
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
611 functions also return an error indicator, usually \NULL{} if they are
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
612 supposed to return a pointer, or -1 if they return an integer
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
613 (exception: the \code{PyArg_Parse*()} functions return 1 for success and
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
614 0 for failure). When a function must fail because of some function it
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
615 called failed, it generally doesn't set the error indicator; the
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
616 function it called already set it.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
617
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
618 The error indicator consists of three Python objects corresponding to
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
619 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
620 \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
621 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
622 for each thread.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
623
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
624 % 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
625 % 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
626
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
627 \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
628 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
629 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
630 (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
631 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
632
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
633 \begin{cfuncdesc}{PyObject *}{PyErr_Occurred}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
634 Test whether the error indicator is set. If set, return the exception
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
635 \code{type} (the first argument to the last call to one of the
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
636 \code{PyErr_Set*()} functions or to \code{PyErr_Restore()}). If not
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
637 set, return \NULL{}. You do not own a reference to the return value,
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
638 so you do not need to \code{Py_DECREF()} it. Note: do not compare the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
639 return value to a specific exception; use
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
640 \code{PyErr_ExceptionMatches} instead, shown below.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
641 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
642
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
643 \begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
644 \strong{(NEW in 1.5a4!)}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
645 Equivalent to
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
646 \code{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
647 This should only be called when an exception is actually set.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
648 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
649
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
650 \begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
651 \strong{(NEW in 1.5a4!)}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
652 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
653 \var{exc}. If \var{exc} is a class object, this also returns true
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
654 when \var{given} is a subclass. If \var{exc} is a tuple, all
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
655 exceptions in the tuple (and recursively in subtuples) are searched
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
656 for a match. This should only be called when an exception is actually
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
657 set.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
658 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
659
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
660 \begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
661 \strong{(NEW in 1.5a4!)}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
662 Under certain circumstances, the values returned by
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
663 \code{PyErr_Fetch()} below can be ``unnormalized'', meaning that
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
664 \var{*exc} is a class object but \var{*val} is not an instance of the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
665 same class. This function can be used to instantiate the class in
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
666 that case. If the values are already normalized, nothing happens.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
667 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
668
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
669 \begin{cfuncdesc}{void}{PyErr_Clear}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
670 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
671 is no effect.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
672 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
673
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
674 \begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue, PyObject **ptraceback}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
675 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
676 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
677 \NULL{}. If it is set, it will be cleared and you own a reference to
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
678 each object retrieved. The value and traceback object may be \NULL{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
679 even when the type object is not. \strong{Note:} this function is
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
680 normally only used by code that needs to handle exceptions or by code
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
681 that needs to save and restore the error indicator temporarily.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
682 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
683
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
684 \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, PyObject *traceback}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
685 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
686 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
687 \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
688 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
689 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
690 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
691 (Violating these rules will cause subtle problems later.) This call
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
692 takes away a reference to each object, i.e. you must own a reference
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
693 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
694 these references. (If you don't understand this, don't use this
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
695 function. I warned you.) \strong{Note:} this function is normally
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
696 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
697 temporarily.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
698 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
699
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
700 \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
701 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
702 argument specifies the exception type; it is normally one of the
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
703 standard exceptions, e.g. \code{PyExc_RuntimeError}. You need not
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
704 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
705 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
706 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
707
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
708 \begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
709 This function is similar to \code{PyErr_SetString()} but lets you
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
710 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
711 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
712 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
713
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
714 \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
715 This is a shorthand for \code{PyErr_SetString(\var{type}, Py_None}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
716 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
717
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
718 \begin{cfuncdesc}{int}{PyErr_BadArgument}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
719 This is a shorthand for \code{PyErr_SetString(PyExc_TypeError,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
720 \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
721 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
722 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
723
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
724 \begin{cfuncdesc}{PyObject *}{PyErr_NoMemory}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
725 This is a shorthand for \code{PyErr_SetNone(PyExc_MemoryError)}; it
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
726 returns \NULL{} so an object allocation function can write
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
727 \code{return PyErr_NoMemory();} when it runs out of memory.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
728 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
729
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
730 \begin{cfuncdesc}{PyObject *}{PyErr_SetFromErrno}{PyObject *type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
731 This is a convenience function to raise an exception when a C library
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
732 function has returned an error and set the C variable \code{errno}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
733 It constructs a tuple object whose first item is the integer
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
734 \code{errno} value and whose second item is the corresponding error
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
735 message (gotten from \code{strerror()}), and then calls
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
736 \code{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
737 the \code{errno} value is \code{EINTR}, indicating an interrupted
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
738 system call, this calls \code{PyErr_CheckSignals()}, and if that set
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
739 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
740 returns \NULL{}, so a wrapper function around a system call can write
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
741 \code{return PyErr_NoMemory();} when the system call returns an error.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
742 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
743
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
744 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
745 This is a shorthand for \code{PyErr_SetString(PyExc_TypeError,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
746 \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
747 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
748 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
749 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
750
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
751 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
752 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
753 whether a signal has been sent to the processes and if so, invokes the
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
754 corresponding signal handler. If the \code{signal} module is
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
755 supported, this can invoke a signal handler written in Python. In all
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
756 cases, the default effect for \code{SIGINT} is to raise the
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
757 \code{KeyboadInterrupt} exception. If an exception is raised the
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
758 error indicator is set and the function returns 1; otherwise the
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
759 function returns 0. The error indicator may or may not be cleared if
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
760 it was previously set.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
761 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
762
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
763 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
764 This function is obsolete (XXX or platform dependent?). It simulates
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
765 the effect of a \code{SIGINT} signal arriving -- the next time
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
766 \code{PyErr_CheckSignals()} is called, \code{KeyboadInterrupt} will be
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
767 raised.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
768 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
769
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
770 \begin{cfuncdesc}{PyObject *}{PyErr_NewException}{char *name,
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
771 PyObject *base, PyObject *dict}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
772 \strong{(NEW in 1.5a4!)}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
773 This utility function creates and returns a new exception object. The
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
774 \var{name} argument must be the name of the new exception, a C string
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
775 of the form \code{module.class}. The \var{base} and \var{dict}
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
776 arguments are normally \NULL{}. Normally, this creates a class
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
777 object derived from the root for all exceptions, the built-in name
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
778 \code{Exception} (accessible in C as \code{PyExc_Exception}). In this
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
779 case the \code{__module__} attribute of the new class is set to the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
780 first part (up to the last dot) of the \var{name} argument, and the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
781 class name is set to the last part (after the last dot). When the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
782 user has specified the \code{-X} command line option to use string
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
783 exceptions, for backward compatibility, or when the \var{base}
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
784 argument is not a class object (and not \NULL{}), a string object
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
785 created from the entire \var{name} argument is returned. The
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
786 \var{base} argument can be used to specify an alternate base class.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
787 The \var{dict} argument can be used to specify a dictionary of class
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
788 variables and methods.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
789 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
790
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
791
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
792 \section{Standard Exceptions}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
793
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
794 All standard Python exceptions are available as global variables whose
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
795 names are \code{PyExc_} followed by the Python exception name.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
796 These have the type \code{PyObject *}; they are all string objects.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
797 For completeness, here are all the variables (the first four are new
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
798 in Python 1.5a4):
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
799 \code{PyExc_Exception},
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
800 \code{PyExc_StandardError},
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
801 \code{PyExc_ArithmeticError},
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
802 \code{PyExc_LookupError},
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
803 \code{PyExc_AssertionError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
804 \code{PyExc_AttributeError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
805 \code{PyExc_EOFError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
806 \code{PyExc_FloatingPointError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
807 \code{PyExc_IOError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
808 \code{PyExc_ImportError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
809 \code{PyExc_IndexError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
810 \code{PyExc_KeyError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
811 \code{PyExc_KeyboardInterrupt},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
812 \code{PyExc_MemoryError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
813 \code{PyExc_NameError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
814 \code{PyExc_OverflowError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
815 \code{PyExc_RuntimeError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
816 \code{PyExc_SyntaxError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
817 \code{PyExc_SystemError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
818 \code{PyExc_SystemExit},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
819 \code{PyExc_TypeError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
820 \code{PyExc_ValueError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
821 \code{PyExc_ZeroDivisionError}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
822
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
823
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
824 \chapter{Utilities}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
825
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
826 The functions in this chapter perform various utility tasks, such as
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
827 parsing function arguments and constructing Python values from C
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
828 values.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
829
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
830 \section{OS Utilities}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
831
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
832 \begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
833 Return true (nonzero) if the standard I/O file \code{fp} with name
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
834 \code{filename} is deemed interactive. This is the case for files for
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
835 which \code{isatty(fileno(fp))} is true. If the global flag
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
836 \code{Py_InteractiveFlag} is true, this function also returns true if
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
837 the \code{name} pointer is \NULL{} or if the name is equal to one of
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
838 the strings \code{"<stdin>"} or \code{"???"}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
839 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
840
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
841 \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
842 Return the time of last modification of the file \code{filename}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
843 The result is encoded in the same way as the timestamp returned by
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
844 the standard C library function \code{time()}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
845 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
846
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
847
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
848 \section{Importing modules}
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}{PyObject *}{PyImport_ImportModule}{char *name}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
851 This is a simplified interface to \code{PyImport_ImportModuleEx}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
852 below, leaving the \var{globals} and \var{locals} arguments set to
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
853 \NULL{}. When the \var{name} argument contains a dot (i.e., when
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
854 it specifies a submodule of a package), the \var{fromlist} argument is
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
855 set to the list \code{['*']} so that the return value is the named
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
856 module rather than the top-level package containing it as would
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
857 otherwise be the case. (Unfortunately, this has an additional side
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
858 effect when \var{name} in fact specifies a subpackage instead of a
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
859 submodule: the submodules specified in the package's \code{__all__}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
860 variable are loaded.) Return a new reference to the imported module,
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
861 or \NULL{} with an exception set on failure (the module may still
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
862 be created in this case).
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
863 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
864
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
865 \begin{cfuncdesc}{PyObject *}{PyImport_ImportModuleEx}{char *name, PyObject *globals, PyObject *locals, PyObject *fromlist}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
866 \strong{(NEW in 1.5a4!)}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
867 Import a module. This is best described by referring to the built-in
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
868 Python function \code{__import()__}, as the standard
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
869 \code{__import__()} function calls this function directly.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
870
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
871 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
872 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
873 (the module may still be created in this case). Like for
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
874 \code{__import__()}, the return value when a submodule of a package
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
875 was requested is normally the top-level package, unless a non-empty
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
876 \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
877 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
878
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
879 \begin{cfuncdesc}{PyObject *}{PyImport_Import}{PyObject *name}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
880 This is a higher-level interface that calls the current ``import hook
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
881 function''. It invokes the \code{__import__()} function from the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
882 \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
883 import is done using whatever import hooks are installed in the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
884 current environment, e.g. by \code{rexec} or \code{ihooks}.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
885 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
886
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
887 \begin{cfuncdesc}{PyObject *}{PyImport_ReloadModule}{PyObject *m}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
888 Reload a module. This is best described by referring to the built-in
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
889 Python function \code{reload()}, as the standard \code{reload()}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
890 function calls this function directly. Return a new reference to 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
891 reloaded module, or \NULL{} with an exception set on failure (the
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
892 module still exists in this case).
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
893 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
894
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
895 \begin{cfuncdesc}{PyObject *}{PyImport_AddModule}{char *name}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
896 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
897 \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
898 check the modules dictionary if there's one there, and if not, create
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
899 a new one and insert in in the modules dictionary. Because the former
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
900 action is most common, this does not return a new reference, and you
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
901 do not own the returned reference. Return \NULL{} with an
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
902 exception set on failure.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
903 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
904
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
905 \begin{cfuncdesc}{PyObject *}{PyImport_ExecCodeModule}{char *name, PyObject *co}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
906 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
907 code object read from a Python bytecode file or obtained from the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
908 built-in function \code{compile()}, load the module. Return a new
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
909 reference to the module object, or \NULL{} with an exception set
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
910 if an error occurred (the module may still be created in this case).
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
911 (This function would reload the module if it was already imported.)
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
912 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
913
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
914 \begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
915 Return the magic number for Python bytecode files (a.k.a. \code{.pyc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
916 and \code{.pyo} files). The magic number should be present in the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
917 first four bytes of the bytecode file, in little-endian byte order.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
918 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
919
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
920 \begin{cfuncdesc}{PyObject *}{PyImport_GetModuleDict}{}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
921 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
922 (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
923 variable.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
924 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
925
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
926 \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
927 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
928 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
929
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
930 \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
931 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
932 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
933
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
934 \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
935 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
936 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
937
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
938 \begin{cvardesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
939 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
940 \end{cvardesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
941
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
942 \begin{cvardesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
943 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
944 \end{cvardesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
945
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
946 \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
947 Load a frozen module. Return \code{1} for success, \code{0} if the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
948 module is not found, and \code{-1} with an exception set if the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
949 initialization failed. To access the imported module on a successful
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
950 load, use \code{PyImport_ImportModule())}.
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
951 (Note the misnomer -- this function would reload the module if it was
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
952 already imported.)
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
953 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
954
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
955 \begin{ctypedesc}{struct _frozen}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
956 This is the structure type definition for frozen module descriptors,
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
957 as generated by the \code{freeze} utility (see \file{Tools/freeze/} in
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
958 the Python source distribution). Its definition is:
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
959 \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
960 struct _frozen {
6480
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
961 char *name;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
962 unsigned char *code;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
963 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
964 };
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
965 \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
966 \end{ctypedesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
967
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
968 \begin{cvardesc}{struct _frozen *}{PyImport_FrozenModules}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
969 This pointer is initialized to point to an array of \code{struct
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
970 _frozen} records, terminated by one whose members are all \NULL{}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
971 or zero. When a frozen module is imported, it is searched in this
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
972 table. Third party code could play tricks with this to provide a
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
973 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
974 \end{cvardesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
975
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
976
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
977 \chapter{Debugging}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
978
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
979 XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
980
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
981
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
982 \chapter{The Very High Level Layer}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
983
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
984 The functions in this chapter will let you execute Python source code
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
985 given in a file or a buffer, but they will not let you interact in a
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
986 more detailed way with the interpreter.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
987
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
988 \begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
989 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
990
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
991 \begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
992 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
993
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
994 \begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
995 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
996
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
997 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
998 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
999
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1000 \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1001 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1002
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1003 \begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1004 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1005
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1006 \begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1007 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1008
6126
b44934c20125 Fix some badly botched prototypes for PyRun* c.s.
Guido van Rossum <guido@python.org>
parents: 6084
diff changeset
1009 \begin{cfuncdesc}{}{PyObject *PyRun_String}{char *, int, PyObject *, PyObject *}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1010 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1011
6126
b44934c20125 Fix some badly botched prototypes for PyRun* c.s.
Guido van Rossum <guido@python.org>
parents: 6084
diff changeset
1012 \begin{cfuncdesc}{}{PyObject *PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1013 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1014
6126
b44934c20125 Fix some badly botched prototypes for PyRun* c.s.
Guido van Rossum <guido@python.org>
parents: 6084
diff changeset
1015 \begin{cfuncdesc}{}{PyObject *Py_CompileString}{char *, char *, int}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1016 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1017
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1018
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1019 \chapter{Abstract Objects Layer}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1020
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1021 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
1022 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
1023 numerical types, or all sequence types). When used on object types
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1024 for which they do not apply, they will flag a Python exception.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1025
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1026 \section{Object Protocol}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1027
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1028 \begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1029 Print an object \code{o}, on file \code{fp}. Returns -1 on error
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1030 The flags argument is used to enable certain printing
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1031 options. The only option currently supported is \code{Py_Print_RAW}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1032 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1033
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1034 \begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1035 Returns 1 if o has the attribute attr_name, and 0 otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1036 This is equivalent to the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1037 \code{hasattr(o,attr_name)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1038 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
1039 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1040
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1041 \begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
1042 Retrieve an attributed named attr_name from object o.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1043 Returns the attribute value on success, or \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1044 This is the equivalent of the Python expression: \code{o.attr_name}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1045 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1046
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1047
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1048 \begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1049 Returns 1 if o has the attribute attr_name, and 0 otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1050 This is equivalent to the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1051 \code{hasattr(o,attr_name)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1052 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
1053 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1054
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1055
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1056 \begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1057 Retrieve an attributed named attr_name form object o.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1058 Returns the attribute value on success, or \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1059 This is the equivalent of the Python expression: o.attr_name.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1060 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1061
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1062
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1063 \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, char *attr_name, PyObject *v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1064 Set the value of the attribute named \code{attr_name}, for object \code{o},
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1065 to the value \code{v}. Returns -1 on failure. This is
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1066 the equivalent of the Python statement: \code{o.attr_name=v}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1067 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1068
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1069
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1070 \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, PyObject *attr_name, PyObject *v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1071 Set the value of the attribute named \code{attr_name}, for
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1072 object \code{o},
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1073 to the value \code{v}. Returns -1 on failure. This is
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1074 the equivalent of the Python statement: \code{o.attr_name=v}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1075 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1076
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1077
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1078 \begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1079 Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1080 failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1081 statement: \code{del o.attr_name}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1082 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1083
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1084
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1085 \begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1086 Delete attribute named \code{attr_name}, for object \code{o}. Returns -1 on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1087 failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1088 statement: \code{del o.attr_name}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1089 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1090
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1091
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1092 \begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1093 Compare the values of \code{o1} and \code{o2} using a routine provided by
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1094 \code{o1}, if one exists, otherwise with a routine provided by \code{o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1095 The result of the comparison is returned in \code{result}. Returns
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1096 -1 on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1097 statement: \code{result=cmp(o1,o2)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1098 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1099
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1100
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1101 \begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1102 Compare the values of \code{o1} and \code{o2} using a routine provided by
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1103 \code{o1}, if one exists, otherwise with a routine provided by \code{o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1104 Returns the result of the comparison on success. On error,
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1105 the value returned is undefined. This is equivalent to the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1106 Python expression: \code{cmp(o1,o2)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1107 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1108
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1109
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1110 \begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1111 Compute the string representation of object, \code{o}. Returns the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1112 string representation on success, \NULL{} on failure. This is
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1113 the equivalent of the Python expression: \code{repr(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1114 Called by the \code{repr()} built-in function and by reverse quotes.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1115 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1116
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1117
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1118 \begin{cfuncdesc}{PyObject*}{PyObject_Str}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1119 Compute the string representation of object, \code{o}. Returns the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1120 string representation on success, \NULL{} on failure. This is
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1121 the equivalent of the Python expression: \code{str(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1122 Called by the \code{str()} built-in function and by the \code{print}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1123 statement.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1124 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1125
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1126
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1127 \begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1128 Determine if the object \code{o}, is callable. Return 1 if the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1129 object is callable and 0 otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1130 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
1131 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1132
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1133
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1134 \begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, PyObject *args}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1135 Call a callable Python object \code{callable_object}, with
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1136 arguments given by the tuple \code{args}. If no arguments are
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1137 needed, then args may be \NULL{}. Returns the result of the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1138 call on success, or \NULL{} on failure. This is the equivalent
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1139 of the Python expression: \code{apply(o, args)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1140 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1141
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1142 \begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, char *format, ...}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1143 Call a callable Python object \code{callable_object}, with a
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1144 variable number of C arguments. The C arguments are described
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1145 using a mkvalue-style format string. The format may be \NULL{},
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1146 indicating that no arguments are provided. Returns the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1147 result of the call on success, or \NULL{} on failure. This is
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1148 the equivalent of the Python expression: \code{apply(o,args)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1149 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1150
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1151
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1152 \begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, char *m, char *format, ...}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1153 Call the method named \code{m} of object \code{o} with a variable number of
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1154 C arguments. The C arguments are described by a mkvalue
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1155 format string. The format may be \NULL{}, indicating that no
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1156 arguments are provided. Returns the result of the call on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1157 success, or \NULL{} on failure. This is the equivalent of the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1158 Python expression: \code{o.method(args)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1159 Note that Special method names, such as "\code{__add__}",
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1160 "\code{__getitem__}", and so on are not supported. The specific
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1161 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
1162 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1163
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1164
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1165 \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1166 Compute and return the hash value of an object \code{o}. On
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1167 failure, return -1. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1168 expression: \code{hash(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1169 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1170
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1171
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1172 \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1173 Returns 1 if the object \code{o} is considered to be true, and
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1174 0 otherwise. This is equivalent to the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1175 \code{not not o}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1176 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
1177 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1178
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1179
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1180 \begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1181 On success, returns a type object corresponding to the object
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1182 type of object \code{o}. On failure, returns \NULL{}. This is
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1183 equivalent to the Python expression: \code{type(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1184 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1185
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1186 \begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1187 Return the length of object \code{o}. If the object \code{o} provides
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1188 both sequence and mapping protocols, the sequence length is
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1189 returned. On error, -1 is returned. This is the equivalent
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1190 to the Python expression: \code{len(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1191 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1192
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1193
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1194 \begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1195 Return element of \code{o} corresponding to the object \code{key} or \NULL{}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1196 on failure. This is the equivalent of the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1197 \code{o[key]}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1198 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1199
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1200
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1201 \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, PyObject *key, PyObject *v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1202 Map the object \code{key} to the value \code{v}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1203 Returns -1 on failure. This is the equivalent
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1204 of the Python statement: \code{o[key]=v}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1205 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1206
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1207
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1208 \begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key, PyObject *v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1209 Delete the mapping for \code{key} from \code{*o}. Returns -1
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1210 on failure.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
1211 This is the equivalent of the Python statement: \code{del o[key]}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1212 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1213
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1214
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1215 \section{Number Protocol}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1216
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1217 \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1218 Returns 1 if the object \code{o} provides numeric protocols, and
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1219 false otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1220 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
1221 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1222
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1223
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1224 \begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1225 Returns the result of adding \code{o1} and \code{o2}, or null on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1226 This is the equivalent of the Python expression: \code{o1+o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1227 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1228
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1229
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1230 \begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1231 Returns the result of subtracting \code{o2} from \code{o1}, or null on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1232 failure. This is the equivalent of the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1233 \code{o1-o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1234 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1235
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1236
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1237 \begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1238 Returns the result of multiplying \code{o1} and \code{o2}, or null on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1239 failure. This is the equivalent of the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1240 \code{o1*o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1241 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1242
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1243
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1244 \begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1245 Returns the result of dividing \code{o1} by \code{o2}, or null on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1246 This is the equivalent of the Python expression: \code{o1/o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1247 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1248
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1249
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1250 \begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1251 Returns the remainder of dividing \code{o1} by \code{o2}, or null on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1252 failure. This is the equivalent of the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1253 \code{o1\%o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1254 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1255
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1256
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1257 \begin{cfuncdesc}{PyObject*}{PyNumber_Divmod}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1258 See the built-in function divmod. Returns \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1259 This is the equivalent of the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1260 \code{divmod(o1,o2)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1261 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1262
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1263
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1264 \begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, PyObject *o2, PyObject *o3}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1265 See the built-in function pow. Returns \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1266 This is the equivalent of the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1267 \code{pow(o1,o2,o3)}, where \code{o3} is optional.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1268 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1269
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1270
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1271 \begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1272 Returns the negation of \code{o} on success, or null on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1273 This is the equivalent of the Python expression: \code{-o}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1274 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1275
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1276
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1277 \begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1278 Returns \code{o} on success, or \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1279 This is the equivalent of the Python expression: \code{+o}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1280 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1281
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1282
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1283 \begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1284 Returns the absolute value of \code{o}, or null on failure. This is
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1285 the equivalent of the Python expression: \code{abs(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1286 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1287
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1288
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1289 \begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1290 Returns the bitwise negation of \code{o} on success, or \NULL{} on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1291 failure. This is the equivalent of the Python expression:
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
1292 \code{\~o}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1293 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1294
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1295
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1296 \begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1297 Returns the result of left shifting \code{o1} by \code{o2} on success, or
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1298 \NULL{} on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1299 expression: \code{o1 << o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1300 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1301
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1302
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1303 \begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1304 Returns the result of right shifting \code{o1} by \code{o2} on success, or
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1305 \NULL{} on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1306 expression: \code{o1 >> o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1307 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1308
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1309
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1310 \begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1311 Returns the result of "anding" \code{o2} and \code{o2} on success and \NULL{}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1312 on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1313 expression: \code{o1 and o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1314 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1315
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1316
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1317 \begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1318 Returns the bitwise exclusive or of \code{o1} by \code{o2} on success, or
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1319 \NULL{} on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1320 expression: \code{o1\^{ }o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1321 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1322
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1323 \begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
1324 Returns the result of \code{o1} and \code{o2} on success, or \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
1325 failure. This is the equivalent of the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1326 \code{o1 or o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1327 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1328
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1329
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1330 \begin{cfuncdesc}{PyObject*}{PyNumber_Coerce}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1331 This function takes the addresses of two variables of type
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1332 \code{PyObject*}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1333
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1334 If the objects pointed to by \code{*p1} and \code{*p2} have the same type,
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1335 increment their reference count and return 0 (success).
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1336 If the objects can be converted to a common numeric type,
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1337 replace \code{*p1} and \code{*p2} by their converted value (with 'new'
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1338 reference counts), and return 0.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1339 If no conversion is possible, or if some other error occurs,
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1340 return -1 (failure) and don't increment the reference counts.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1341 The call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1342 statement \code{o1, o2 = coerce(o1, o2)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1343 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1344
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1345
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1346 \begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1347 Returns the \code{o} converted to an integer object on success, or
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1348 \NULL{} on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1349 expression: \code{int(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1350 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1351
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1352
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1353 \begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1354 Returns the \code{o} converted to a long integer object on success,
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1355 or \NULL{} on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1356 expression: \code{long(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1357 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1358
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1359
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1360 \begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1361 Returns the \code{o} converted to a float object on success, or \NULL{}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1362 on failure. This is the equivalent of the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1363 \code{float(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1364 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1365
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1366
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1367 \section{Sequence protocol}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1368
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1369 \begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1370 Return 1 if the object provides sequence protocol, and 0
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1371 otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1372 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
1373 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1374
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1375
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1376 \begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1377 Return the concatination of \code{o1} and \code{o2} on success, and \NULL{} on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1378 failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1379 expression: \code{o1+o2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1380 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1381
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1382
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1383 \begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
1384 Return the result of repeating sequence object \code{o} \code{count} times,
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1385 or \NULL{} on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1386 expression: \code{o*count}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1387 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1388
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1389
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1390 \begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1391 Return the ith element of \code{o}, or \NULL{} on failure. This is the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1392 equivalent of the Python expression: \code{o[i]}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1393 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1394
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1395
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1396 \begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1397 Return the slice of sequence object \code{o} between \code{i1} and \code{i2}, or
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1398 \NULL{} on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1399 expression, \code{o[i1:i2]}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1400 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1401
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1402
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1403 \begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1404 Assign object \code{v} to the \code{i}th element of \code{o}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1405 Returns -1 on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1406 statement, \code{o[i]=v}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1407 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1408
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1409 \begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1410 Delete the \code{i}th element of object \code{v}. Returns
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1411 -1 on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1412 statement: \code{del o[i]}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1413 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1414
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1415 \begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, int i2, PyObject *v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1416 Assign the sequence object \code{v} to the slice in sequence
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1417 object \code{o} from \code{i1} to \code{i2}. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1418 statement, \code{o[i1:i2]=v}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1419 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1420
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1421 \begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1422 Delete the slice in sequence object, \code{o}, from \code{i1} to \code{i2}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1423 Returns -1 on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1424 statement: \code{del o[i1:i2]}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1425 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1426
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1427 \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1428 Returns the \code{o} as a tuple on success, and \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1429 This is equivalent to the Python expression: \code{tuple(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1430 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1431
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1432 \begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1433 Return the number of occurrences of \code{value} on \code{o}, that is,
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1434 return the number of keys for which \code{o[key]==value}. On
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1435 failure, return -1. This is equivalent to the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1436 expression: \code{o.count(value)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1437 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1438
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1439 \begin{cfuncdesc}{int}{PySequence_In}{PyObject *o, PyObject *value}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1440 Determine if \code{o} contains \code{value}. If an item in \code{o} is equal to
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1441 \code{value}, return 1, otherwise return 0. On error, return -1. This
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1442 is equivalent to the Python expression: \code{value in o}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1443 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1444
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1445 \begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
1446 Return the first index for which \code{o[i]==value}. On error,
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1447 return -1. This is equivalent to the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1448 expression: \code{o.index(value)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1449 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1450
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1451 \section{Mapping protocol}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1452
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1453 \begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1454 Return 1 if the object provides mapping protocol, and 0
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1455 otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1456 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
1457 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1460 \begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1461 Returns the number of keys in object \code{o} on success, and -1 on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1462 failure. For objects that do not provide sequence protocol,
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1463 this is equivalent to the Python expression: \code{len(o)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1464 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1467 \begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1468 Remove the mapping for object \code{key} from the object \code{o}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1469 Return -1 on failure. This is equivalent to
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1470 the Python statement: \code{del o[key]}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1471 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1472
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1473
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}{PyMapping_DelItem}{PyObject *o, PyObject *key}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1475 Remove the mapping for object \code{key} from the object \code{o}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1476 Return -1 on failure. This is equivalent to
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1477 the Python statement: \code{del o[key]}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1478 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1479
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1480
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1481 \begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1482 On success, return 1 if the mapping object has the key \code{key}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1483 and 0 otherwise. This is equivalent to the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1484 \code{o.has_key(key)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1485 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
1486 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1487
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1488
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1489 \begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1490 Return 1 if the mapping object has the key \code{key}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1491 and 0 otherwise. This is equivalent to the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1492 \code{o.has_key(key)}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1493 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
1494 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1495
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 \begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1498 On success, return a list of the keys in object \code{o}. On
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1499 failure, return \NULL{}. This is equivalent to the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1500 expression: \code{o.keys()}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1501 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1502
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1503
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1504 \begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1505 On success, return a list of the values in object \code{o}. On
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1506 failure, return \NULL{}. This is equivalent to the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1507 expression: \code{o.values()}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1508 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1509
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1510
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1511 \begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1512 On success, return a list of the items in object \code{o}, where
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1513 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
1514 failure, return \NULL{}. This is equivalent to the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1515 expression: \code{o.items()}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1516 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1517
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1518 \begin{cfuncdesc}{int}{PyMapping_Clear}{PyObject *o}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1519 Make object \code{o} empty. Returns 1 on success and 0 on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1520 This is equivalent to the Python statement:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1521 \code{for key in o.keys(): del o[key]}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1522 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1523
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 \begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1526 Return element of \code{o} corresponding to the object \code{key} or \NULL{}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1527 on failure. This is the equivalent of the Python expression:
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1528 \code{o[key]}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1529 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1530
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1531 \begin{cfuncdesc}{PyObject*}{PyMapping_SetItemString}{PyObject *o, char *key, PyObject *v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1532 Map the object \code{key} to the value \code{v} in object \code{o}. Returns
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1533 -1 on failure. This is the equivalent of the Python
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1534 statement: \code{o[key]=v}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1535 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1537
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1538 \section{Constructors}
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}{PyObject*}{PyFile_FromString}{char *file_name, char *mode}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1541 On success, returns a new file object that is opened on the
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1542 file given by \code{file_name}, with a file mode given by \code{mode},
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1543 where \code{mode} has the same semantics as the standard C routine,
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1544 fopen. On failure, return -1.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1545 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1546
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1547 \begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, char *file_name, char *mode, int close_on_del}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1548 Return a new file object for an already opened standard C
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1549 file pointer, \code{fp}. A file name, \code{file_name}, and open mode,
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1550 \code{mode}, must be provided as well as a flag, \code{close_on_del}, that
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1551 indicates whether the file is to be closed when the file
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1552 object is destroyed. On failure, return -1.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1553 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1554
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1555 \begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1556 Returns a new float object with the value \code{v} on success, and
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1557 \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1558 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1559
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1560 \begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1561 Returns a new int object with the value \code{v} on success, and
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1562 \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1563 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1564
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1565 \begin{cfuncdesc}{PyObject*}{PyList_New}{int l}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1566 Returns a new list of length \code{l} on success, and \NULL{} on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1567 failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1568 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1569
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1570 \begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1571 Returns a new long object with the value \code{v} on success, and
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1572 \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1573 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1574
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1575 \begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1576 Returns a new long object with the value \code{v} on success, and
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1577 \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1578 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1579
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1580 \begin{cfuncdesc}{PyObject*}{PyDict_New}{}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1581 Returns a new empty dictionary on success, and \NULL{} on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1582 failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1583 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1584
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1585 \begin{cfuncdesc}{PyObject*}{PyString_FromString}{char *v}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1586 Returns a new string object with the value \code{v} on success, and
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1587 \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1588 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1589
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1590 \begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{char *v, int l}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1591 Returns a new string object with the value \code{v} and length \code{l}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1592 on success, and \NULL{} on failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1593 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1594
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1595 \begin{cfuncdesc}{PyObject*}{PyTuple_New}{int l}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1596 Returns a new tuple of length \code{l} on success, and \NULL{} on
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1597 failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1598 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1599
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1600
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1601 \chapter{Concrete Objects Layer}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1602
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1603 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
1604 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
1605 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
1606 that it has the right type, you must perform a type check first;
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1607 e.g. to check that an object is a dictionary, use
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1608 \code{PyDict_Check()}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1609
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1610
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1611 \chapter{Defining New Object Types}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1612
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1613 \begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1614 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1615
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1616 \begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1617 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1618
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1619 \begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1620 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1621
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1622 \begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1623 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
1624
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1625 \chapter{Initialization, Finalization, and Threads}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1626
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1627 \begin{cfuncdesc}{void}{Py_Initialize}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1628 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
1629 Python, this should be called before using any other Python/C API
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1630 functions; with the exception of \code{Py_SetProgramName()},
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1631 \code{PyEval_InitThreads()}, \code{PyEval_ReleaseLock()}, and
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1632 \code{PyEval_AcquireLock()}. This initializes the table of loaded
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1633 modules (\code{sys.modules}), and creates the fundamental modules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1634 \code{__builtin__}, \code{__main__} and \code{sys}. It also
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1635 initializes the module search path (\code{sys.path}). It does not set
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1636 \code{sys.argv}; use \code{PySys_SetArgv()} for that. This is a no-op
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1637 when called for a second time (without calling \code{Py_Finalize()}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1638 first). There is no return value; it is a fatal error if the
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1639 initialization fails.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1640 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1641
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1642 \begin{cfuncdesc}{int}{Py_IsInitialized}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1643 \strong{(NEW in 1.5a4!)}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1644 Return true (nonzero) when the Python interpreter has been
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1645 initialized, false (zero) if not. After \code{Py_Finalize()} is
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1646 called, this returns false until \code{Py_Initialize()} is called
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1647 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1648 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1649
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1650 \begin{cfuncdesc}{void}{Py_Finalize}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1651 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1652 Undo all initializations made by \code{Py_Initialize()} and subsequent
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1653 use of Python/C API functions, and destroy all sub-interpreters (see
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1654 \code{Py_NewInterpreter()} below) that were created and not yet
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1655 destroyed since the last call to \code{Py_Initialize()}. Ideally,
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1656 this frees all memory allocated by the Python interpreter. This is a
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1657 no-op when called for a second time (without calling
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1658 \code{Py_Initialize()} again first). There is no return value; errors
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1659 during finalization are ignored.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1660
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1661 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
1662 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
1663 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
1664 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
1665 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
1666 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
1667 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
1668
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1669 \emph{Bugs and caveats:} The destruction of modules and objects in
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1670 modules is done in random order; this may cause destructors
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1671 (\code{__del__} methods) to fail when they depend on other objects
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1672 (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
1673 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
1674 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
1675 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
1676 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
1677 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
1678 routine is called more than once; this can happen if an applcation
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1679 calls \code{Py_Initialize()} and \code{Py_Finalize()} more than once.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1680 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1681
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1682 \begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1683 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1684 Create a new sub-interpreter. This is an (almost) totally separate
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1685 environment for the execution of Python code. In particular, the new
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1686 interpreter has separate, independent versions of all imported
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1687 modules, including the fundamental modules \code{__builtin__},
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1688 \code{__main__} and \code{sys}. The table of loaded modules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1689 (\code{sys.modules}) and the module search path (\code{sys.path}) are
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1690 also separate. The new environment has no \code{sys.argv} variable.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1691 It has new standard I/O stream file objects \code{sys.stdin},
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1692 \code{sys.stdout} and \code{sys.stderr} (however these refer to the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1693 same underlying \code{FILE} structures in the C library).
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1694
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1695 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
1696 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
1697 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
1698 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
1699 \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
1700 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
1701 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
1702 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
1703 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
1704 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
1705
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1706 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
1707 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
1708 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
1709 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
1710 (sub-)interpreter, a new module is initialized and filled with the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1711 contents of this copy; the extension's \code{init} function is not
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1712 called. Note that this is different from what happens when as
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1713 extension is imported after the interpreter has been completely
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1714 re-initialized by calling \code{Py_Finalize()} and
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1715 \code{Py_Initialize()}; in that case, the extension's \code{init}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1716 function \emph{is} called again.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1717
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1718 \emph{Bugs and caveats:} Because sub-interpreters (and the main
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1719 interpreter) are part of the same process, the insulation between them
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1720 isn't perfect -- for example, using low-level file operations like
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1721 \code{os.close()} they can (accidentally or maliciously) affect each
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1722 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
1723 (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
1724 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
1725 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
1726 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
1727 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
1728 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
1729 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
1730 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
1731 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
1732 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
1733 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1734
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1735 \begin{cfuncdesc}{void}{Py_EndInterpreter}{PyThreadState *tstate}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1736 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1737 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
1738 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
1739 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
1740 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
1741 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
1742 before calling this function and is still held when it returns.)
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1743 \code{Py_Finalize()} will destroy all sub-interpreters that haven't
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1744 been explicitly destroyed at that point.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1745 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1746
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1747 \begin{cfuncdesc}{void}{Py_SetProgramName}{char *name}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1748 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1749 This function should be called before \code{Py_Initialize()} is called
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1750 for the first time, if it is called at all. It tells the interpreter
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1751 the value of the \code{argv[0]} argument to the \code{main()} function
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1752 of the program. This is used by \code{Py_GetPath()} and some other
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1753 functions below to find the Python run-time libraries relative to the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1754 interpreter executable. The default value is \code{"python"}. The
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1755 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
1756 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
1757 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
1758 the contents of this storage.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1759 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1760
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1761 \begin{cfuncdesc}{char *}{Py_GetProgramName}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1762 Return the program name set with \code{Py_SetProgramName()}, or the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1763 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
1764 should not modify its value.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1765 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1766
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1767 \begin{cfuncdesc}{char *}{Py_GetPrefix}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1768 Return the ``prefix'' for installed platform-independent files. This
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1769 is derived through a number of complicated rules from the program name
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1770 set with \code{Py_SetProgramName()} and some environment variables;
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1771 for example, if the program name is \code{"/usr/local/bin/python"},
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1772 the prefix is \code{"/usr/local"}. The returned string points into
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1773 static storage; the caller should not modify its value. This
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1774 corresponds to the \code{prefix} variable in the top-level
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1775 \code{Makefile} and the \code{--prefix} argument to the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1776 \code{configure} script at build time. The value is available to
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1777 Python code as \code{sys.prefix}. It is only useful on Unix. See
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1778 also the next function.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1779 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1780
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1781 \begin{cfuncdesc}{char *}{Py_GetExecPrefix}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1782 Return the ``exec-prefix'' for installed platform-\emph{de}pendent
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1783 files. This is derived through a number of complicated rules from the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1784 program name set with \code{Py_SetProgramName()} and some environment
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1785 variables; for example, if the program name is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1786 \code{"/usr/local/bin/python"}, the exec-prefix is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1787 \code{"/usr/local"}. The returned string points into static storage;
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1788 the caller should not modify its value. This corresponds to the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1789 \code{exec_prefix} variable in the top-level \code{Makefile} and the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1790 \code{--exec_prefix} argument to the \code{configure} script at build
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1791 time. The value is available to Python code as
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1792 \code{sys.exec_prefix}. It is only useful on Unix.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1793
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1794 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
1795 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
1796 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
1797 platform dependent files may be installed in the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1798 \code{"/usr/local/plat"} subtree while platform independent may be
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1799 installed in \code{"/usr/local"}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1800
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1801 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
1802 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
1803 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
1804 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
1805 Linux are yet another platform. Different major revisions of the same
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1806 operating system generally also form different platforms. Non-Unix
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1807 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
1808 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
1809 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
1810 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
1811 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
1812
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1813 System administrators will know how to configure the \code{mount} or
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1814 \code{automount} programs to share \code{"/usr/local"} between platforms
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1815 while having \code{"/usr/local/plat"} be a different filesystem for each
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1816 platform.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1817 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1818
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1819 \begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1820 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1821 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
1822 computed as a side-effect of deriving the default module search path
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
1823 from the program name (set by \code{Py_SetProgramName()} above). The
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1824 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
1825 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
1826 \code{sys.executable}.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1827 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1828
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1829 \begin{cfuncdesc}{char *}{Py_GetPath}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1830 Return the default module search path; this is computed from the
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
1831 program name (set by \code{Py_SetProgramName()} above) and some
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1832 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
1833 directory names separated by a platform dependent delimiter character.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1834 The delimiter character is \code{':'} on Unix, \code{';'} on
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
1835 DOS/Windows, and \code{'\\n'} (the ASCII newline character) on
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1836 Macintosh. 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
1837 should not modify its value. The value is available to Python code
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1838 as the list \code{sys.path}, which may be modified to change the
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1839 future search path for loaded modules.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1840
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1841 % XXX should give the exact rules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1842 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1843
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1844 \begin{cfuncdesc}{const char *}{Py_GetVersion}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1845 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
1846 looks something like
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1847
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
1848 \begin{verbatim}
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
1849 "1.5a3 (#67, Aug 1 1997, 22:34:28) [GCC 2.7.2.2]"
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
1850 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1851
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1852 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
1853 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
1854 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
1855 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
1856 Python code as the list \code{sys.version}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1857 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1858
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1859 \begin{cfuncdesc}{const char *}{Py_GetPlatform}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1860 Return the platform identifier for the current platform. On Unix,
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1861 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
1862 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
1863 for Solaris 2.x, which is also known as SunOS 5.x, the value is
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1864 \code{"sunos5"}. On Macintosh, it is \code{"mac"}. On Windows, it
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1865 is \code{"win"}. The returned string points into static storage;
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1866 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
1867 Python code as \code{sys.platform}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1868 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1869
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1870 \begin{cfuncdesc}{const char *}{Py_GetCopyright}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1871 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
1872 for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1873
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1874 \code{"Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam"}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1875
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1876 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
1877 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
1878 \code{sys.copyright}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1879 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1880
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1881 \begin{cfuncdesc}{const char *}{Py_GetCompiler}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1882 Return an indication of the compiler used to build the current Python
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1883 version, in square brackets, for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1884
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1885 \code{"[GCC 2.7.2.2]"}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1886
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1887 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
1888 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
1889 the variable \code{sys.version}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1890 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1891
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1892 \begin{cfuncdesc}{const char *}{Py_GetBuildInfo}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1893 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
1894 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
1895
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
1896 \begin{verbatim}
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
1897 "#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
1898 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1899
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1900 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
1901 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
1902 the variable \code{sys.version}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1903 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1904
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1905 \begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1906 % XXX
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1907 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1908
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1909 % 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
1910
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1911 \section{Thread State and the Global Interpreter Lock}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
1912
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1913 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
1914 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
1915 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
1916 Without the lock, even the simplest operations could cause problems in
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1917 a multi-threaded proram: for example, when two threads simultaneously
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1918 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
1919 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
1920
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1921 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
1922 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
1923 API functions. In order to support multi-threaded Python programs,
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1924 the interpreter regularly release and reacquires the lock -- by
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1925 default, every ten bytecode instructions (this can be changed with
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1926 \code{sys.setcheckinterval()}). The lock is also released and
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1927 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
1928 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
1929 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
1930
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1931 The Python interpreter needs to keep some bookkeeping information
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1932 separate per thread -- for this it uses a data structure called
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1933 PyThreadState. This is new in Python 1.5; in earlier versions, such
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1934 state was stored in global variables, and switching threads could
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1935 cause problems. In particular, exception handling is now thread safe,
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1936 when the application uses \code{sys.exc_info()} to access the exception
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1937 last raised in the current thread.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1938
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1939 There's one global variable left, however: the pointer to the current
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1940 PyThreadState structure. While most thread packages have a way to
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1941 store ``per-thread global data'', Python's internal platform
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1942 independent thread abstraction doesn't support this (yet). Therefore,
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1943 the current thread state must be manipulated explicitly.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1944
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1945 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
1946 interpreter lock has the following simple structure:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1947
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1948 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1949 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
1950 Release the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1951 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1952 Reacquire the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1953 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
1954 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1955
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1956 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
1957
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1958 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1959 Py_BEGIN_ALLOW_THREADS
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1960 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1961 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
1962 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1963
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1964 The BEGIN macro opens a new block and declares a hidden local
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1965 variable; the END macro closes the block. Another advantage of using
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1966 these two macros is that when Python is compiled without thread
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1967 support, they are defined empty, thus saving the thread state and lock
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1968 manipulations.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1969
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1970 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
1971 following code:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1972
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1973 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1974 {
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1975 PyThreadState *_save;
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1976 _save = PyEval_SaveThread();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1977 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1978 PyEval_RestoreThread(_save);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1979 }
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1980 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1981
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1982 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
1983 as follows:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1984
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1985 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1986 {
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1987 PyThreadState *_save;
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1988 _save = PyThreadState_Swap(NULL);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1989 PyEval_ReleaseLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1990 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1991 PyEval_AcquireLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1992 PyThreadState_Swap(_save);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1993 }
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
1994 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1995
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1996 There are some subtle differences; in particular,
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1997 \code{PyEval_RestoreThread()} saves and restores the value of the
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1998 global variable \code{errno}, since the lock manipulation does not
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
1999 guarantee that \code{errno} is left alone. Also, when thread support
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2000 is disabled, \code{PyEval_SaveThread()} and
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2001 \code{PyEval_RestoreThread()} don't manipulate the lock; in this case,
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2002 \code{PyEval_ReleaseLock()} and \code{PyEval_AcquireLock()} are not
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2003 available. (This is done so that dynamically loaded extensions
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2004 compiled with thread support enabled can be loaded by an interpreter
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2005 that was compiled with disabled thread support.)
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2006
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2007 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
2008 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
2009 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
2010 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
2011 lock and store its own thread state in the global variable).
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2012 Reversely, when acquiring the lock and restoring the thread state, the
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2013 lock must be acquired before storing the thread state pointer.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2014
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2015 Why am I going on with so much detail about this? Because when
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2016 threads are created from C, they don't have the global interpreter
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2017 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
2018 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
2019 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
2020 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
2021 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
2022 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
2023 structure.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2024
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2025 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
2026 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
2027 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
2028 interpreter, for example the module administration
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2029 (\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
2030 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
2031 data structure used by the Python main thread (to access the latter,
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2032 you must obtain the thread state and access its \code{interp} member;
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2033 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
2034 thread after Python is initialized).
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2035
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2036 XXX More?
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2037
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2038 \begin{ctypedesc}{PyInterpreterState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2039 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2040 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
2041 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
2042 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
2043 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
2044
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2045 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
2046 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
2047 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
2048 regardless of to which interpreter they belong.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2049 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2050
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2051 \begin{ctypedesc}{PyThreadState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2052 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2053 This data structure represents the state of a single thread. The only
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2054 public data member is \code{PyInterpreterState *interp}, which points
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2055 to this thread's interpreter state.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2056 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2057
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2058 \begin{cfuncdesc}{void}{PyEval_InitThreads}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2059 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
2060 called in the main thread before creating a second thread or engaging
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2061 in any other thread operations such as \code{PyEval_ReleaseLock()} or
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2062 \code{PyEval_ReleaseThread(tstate)}. It is not needed before
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2063 calling \code{PyEval_SaveThread()} or \code{PyEval_RestoreThread()}.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2064
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2065 This is a no-op when called for a second time. It is safe to call
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2066 this function before calling \code{Py_Initialize()}.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2067
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2068 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
2069 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
2070 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
2071 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
2072 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
2073 accesses are safe. Therefore, when this function initializes the
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2074 lock, it also acquires it. Before the Python \code{thread} module
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2075 creates a new thread, knowing that either it has the lock or the lock
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2076 hasn't been created yet, it calls \code{PyEval_InitThreads()}. When
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2077 this call returns, it is guaranteed that the lock has been created and
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2078 that it has acquired it.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2079
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2080 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
2081 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
2082
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2083 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
2084 compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2085 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2086
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2087 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2088 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2089 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
2090 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
2091 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
2092 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2093 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2094
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2095 \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2096 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2097 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
2098 earlier. This function is not available when thread support is
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2099 disabled at
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2100 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2101 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2102
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2103 \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
2104 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2105 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
2106 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
2107 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
2108 deadlock ensues. This function is not available when thread support
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2109 is disabled at
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2110 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2111 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2112
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2113 \begin{cfuncdesc}{void}{PyEval_ReleaseThread}{PyThreadState *tstate}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2114 \strong{(NEW in 1.5a3!)}
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
2115 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
2116 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
2117 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
2118 be \NULL{}, is only used to check that it represents the current
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2119 thread state -- if it isn't, a fatal error is reported. This function
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2120 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
2121 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2122 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2123
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2124 \begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2125 \strong{(Different return type in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2126 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
2127 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
2128 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
2129 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
2130 (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
2131 compile time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2132 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2133
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2134 \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2135 \strong{(Different argument type in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2136 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
2137 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
2138 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
2139 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
2140 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
2141 time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2142 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2143
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2144 % XXX These aren't really C types, but the ctypedesc macro is the simplest!
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2145 \begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2146 This macro expands to
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2147 \code{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2148 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
2149 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
2150 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
2151 disabled at compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2152 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2153
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2154 \begin{ctypedesc}{Py_END_ALLOW_THREADS}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2155 This macro expands to
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2156 \code{PyEval_RestoreThread(_save); \} }.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2157 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
2158 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
2159 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
2160 disabled at compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2161 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2162
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2163 \begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2164 This macro expands to \code{PyEval_RestoreThread(_save);} i.e. it
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2165 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
2166 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
2167 time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2168 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2169
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2170 \begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2171 This macro expands to \code{_save = PyEval_SaveThread();} i.e. it is
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2172 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
2173 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
2174 disabled at compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2175 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2176
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2177 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
2178 is enabled at compile time, and must be called only when the
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2179 interpreter lock has been created. They are all new in 1.5a3.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2180
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2181 \begin{cfuncdesc}{PyInterpreterState *}{PyInterpreterState_New}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2182 Create a new interpreter state object. The interpreter lock must be
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2183 held.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2184 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2185
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2186 \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2187 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
2188 lock must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2189 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2190
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2191 \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2192 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
2193 held. The interpreter state must have been reset with a previous
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2194 call to \code{PyInterpreterState_Clear()}.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2195 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2196
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2197 \begin{cfuncdesc}{PyThreadState *}{PyThreadState_New}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2198 Create a new thread state object belonging to the given interpreter
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2199 object. The interpreter lock must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2200 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2201
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2202 \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2203 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
2204 must be held.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2205 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2206
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2207 \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2208 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
2209 held. The thread state must have been reset with a previous
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2210 call to \code{PyThreadState_Clear()}.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2211 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2212
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2213 \begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2214 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
2215 When the current thread state is \NULL{}, this issues a fatal
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
2216 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
2217 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2218
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2219 \begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2220 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
2221 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
2222 must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2223 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2224
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2225
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2226 \section{Defining New Object Types}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2227
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2228 XXX To be done:
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2229
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2230 PyObject, PyVarObject
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2231
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2232 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
2233
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2234 Typedefs:
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2235 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
2236 intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2237 getreadbufferproc, getwritebufferproc, getsegcountproc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2238 destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2239 setattrofunc, cmpfunc, reprfunc, hashfunc
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2240
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2241 PyNumberMethods
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2242
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2243 PySequenceMethods
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2244
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2245 PyMappingMethods
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2246
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2247 PyBufferProcs
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2248
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2249 PyTypeObject
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2250
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2251 DL_IMPORT
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2252
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2253 PyType_Type
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2254
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2255 Py*_Check
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2256
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2257 Py_None, _Py_NoneStruct
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2258
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2259 _PyObject_New, _PyObject_NewVar
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2260
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2261 PyObject_NEW, PyObject_NEW_VAR
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2262
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2263
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2264 \chapter{Specific Data Types}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2265
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2266 This chapter describes the functions that deal with specific types of
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2267 Python objects. It is structured like the ``family tree'' of Python
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2268 object types.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2269
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2270
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2271 \section{Fundamental Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2272
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2273 This section describes Python type objects and the singleton object
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2274 \code{None}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2275
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2276
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2277 \subsection{Type Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2278
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2279 \begin{ctypedesc}{PyTypeObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2280
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2281 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2282
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2283 \begin{cvardesc}{PyObject *}{PyType_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2284
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2285 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2286
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2287
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2288 \subsection{The None Object}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2289
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2290 \begin{cvardesc}{PyObject *}{Py_None}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2291 XXX macro
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2292 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2293
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2294
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2295 \section{Sequence Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2296
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2297 Generic operations on sequence objects were discussed in the previous
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2298 chapter; this section deals with the specific kinds of sequence
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2299 objects that are intrinsic to the Python language.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2300
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2301
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2302 \subsection{String Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2303
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2304 \begin{ctypedesc}{PyStringObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2305 This subtype of \code{PyObject} represents a Python string object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2306 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2307
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2308 \begin{cvardesc}{PyTypeObject}{PyString_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2309 This instance of \code{PyTypeObject} represents the Python string type.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2310 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2311
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2312 \begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2313
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2314 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2315
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2316 \begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2317
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2318 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2319
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2320 \begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2321
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2322 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2323
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2324 \begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2325
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2326 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2327
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2328 \begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2329
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2330 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2331
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2332 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2333
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2334 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2335
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2336 \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2337
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2338 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2339
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2340 \begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2341
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2342 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2343
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2344 \begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2345
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2346 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2347
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2348 \begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2349
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2350 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2351
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2352 \begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2353
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2354 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2355
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2356 \begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2357
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2358 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2359
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2360 \begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2361
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2362 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2363
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2364
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2365 \subsection{Tuple Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2366
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2367 \begin{ctypedesc}{PyTupleObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2368 This subtype of \code{PyObject} represents a Python tuple object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2369 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2370
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2371 \begin{cvardesc}{PyTypeObject}{PyTuple_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2372 This instance of \code{PyTypeObject} represents the Python tuple type.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2373 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2374
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2375 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2376 Return true if the argument is a tuple object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2377 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2378
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2379 \begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2380 Return a new tuple object of size \code{s}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2381 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2382
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2383 \begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2384 akes a pointer to a tuple object, and returns the size
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2385 of that tuple.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2386 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2387
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2388 \begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2389 returns the object at position \code{pos} in the tuple pointed
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2390 to by \code{p}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2391 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2392
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2393 \begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2394 does the same, but does no checking of it's
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2395 arguments.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2396 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2397
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2398 \begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2399 int low,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2400 int high}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2401 takes a slice of the tuple pointed to by \code{p} from
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2402 \code{low} to \code{high} and returns it as a new tuple.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2403 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2404
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2405 \begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2406 int pos,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2407 PyObject *o}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2408 inserts a reference to object \code{o} at position \code{pos} of
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2409 the tuple pointed to by \code{p}. It returns 0 on success.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2410 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2411
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2412 \begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2413 int pos,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2414 PyObject *o}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2415
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2416 does the same, but does no error checking, and
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2417 should \emph{only} be used to fill in brand new tuples.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2418 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2419
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2420 \begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2421 int new,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2422 int last_is_sticky}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2423 can be used to resize a tuple. Because tuples are
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2424 \emph{supposed} to be immutable, this should only be used if there is only
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2425 one module referencing the object. Do \emph{not} use this if the tuple may
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2426 already be known to some other part of the code. \code{last_is_sticky} is
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2427 a flag - if set, the tuple will grow or shrink at the front, otherwise
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2428 it will grow or shrink at the end. Think of this as destroying the old
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2429 tuple and creating a new one, only more efficiently.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2430 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2431
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2432
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2433 \subsection{List Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2434
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2435 \begin{ctypedesc}{PyListObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2436 This subtype of \code{PyObject} represents a Python list object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2437 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2438
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2439 \begin{cvardesc}{PyTypeObject}{PyList_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2440 This instance of \code{PyTypeObject} represents the Python list type.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2441 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2442
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2443 \begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2444 returns true if it's argument is a \code{PyListObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2445 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2446
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2447 \begin{cfuncdesc}{PyObject *}{PyList_New}{int size}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2448
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2449 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2450
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2451 \begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2452
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2453 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2454
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2455 \begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2456
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2457 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2458
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2459 \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2460
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2461 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2462
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2463 \begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2464
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2465 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2466
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2467 \begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2468
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2469 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2470
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2471 \begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2472
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2473 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2474
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2475 \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2476
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2477 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2478
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2479 \begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2480
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2481 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2482
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2483 \begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2484
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2485 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2486
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2487 \begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2488
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2489 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2490
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2491 \begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2492
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2493 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2494
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2495 \begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2496
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2497 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2498
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2499
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2500 \section{Mapping Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2501
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2502 \subsection{Dictionary Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2503
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2504 \begin{ctypedesc}{PyDictObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2505 This subtype of \code{PyObject} represents a Python dictionary object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2506 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2507
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2508 \begin{cvardesc}{PyTypeObject}{PyDict_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2509 This instance of \code{PyTypeObject} represents the Python dictionary type.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2510 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2511
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2512 \begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2513 returns true if it's argument is a PyDictObject
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2514 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2515
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2516 \begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2517 returns a new empty dictionary.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2518 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2519
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2520 \begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2521 empties an existing dictionary and deletes it.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2522 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2523
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2524 \begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2525 PyObject *key,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2526 PyObject *val}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2527 inserts \code{value} into the dictionary with a key of
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2528 \code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2529 be hashable.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2530 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2531
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2532 \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2533 char *key,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2534 PyObject *val}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2535 inserts \code{value} into the dictionary using \code{key}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2536 as a key. \code{key} should be a char *
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2537 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2538
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2539 \begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2540 removes the entry in dictionary \code{p} with key \code{key}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2541 \code{key} is a PyObject.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2542 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2543
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2544 \begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2545 removes the entry in dictionary \code{p} which has a key
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2546 specified by the \code{char *}\code{key}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2547 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2548
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2549 \begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2550 returns the object from dictionary \code{p} which has a key
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2551 \code{key}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2552 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2553
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2554 \begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2555 does the same, but \code{key} is specified as a
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2556 \code{char *}, rather than a \code{PyObject *}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2557 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2558
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2559 \begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2560 returns a PyListObject containing all the items
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2561 from the dictionary, as in the mapping method \code{items()} (see the Reference
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2562 Guide)
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2563 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2564
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2565 \begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2566 returns a PyListObject containing all the keys
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2567 from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide)
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2568 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2569
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2570 \begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2571 returns a PyListObject containing all the values
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2572 from the dictionary, as in the mapping method \code{values()} (see the Reference Guide)
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2573 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2574
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2575 \begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2576 returns the number of items in the dictionary.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2577 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2578
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2579 \begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2580 int ppos,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2581 PyObject **pkey,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2582 PyObject **pvalue}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2583
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2584 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2585
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2586
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2587 \section{Numeric Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2589 \subsection{Plain Integer Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2590
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2591 \begin{ctypedesc}{PyIntObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2592 This subtype of \code{PyObject} represents a Python integer object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2593 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2594
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2595 \begin{cvardesc}{PyTypeObject}{PyInt_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2596 This instance of \code{PyTypeObject} represents the Python plain
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2597 integer type.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2598 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2599
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2600 \begin{cfuncdesc}{int}{PyInt_Check}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2601
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2602 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2603
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2604 \begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2605 creates a new integer object with a value of \code{ival}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2606
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2607 The current implementation keeps an array of integer objects for all
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2608 integers between -1 and 100, when you create an int in that range you
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2609 actually just get back a reference to the existing object. So it should
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2610 be possible to change the value of 1. I suspect the behaviour of python
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2611 in this case is undefined. :-)
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2612 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2613
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2614 \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2615 returns the value of the object \code{io}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2616 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2617
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2618 \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2619 will first attempt to cast the object to a PyIntObject, if
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2620 it is not already one, and the return it's value.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2621 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2622
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2623 \begin{cfuncdesc}{long}{PyInt_GetMax}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2624 returns the systems idea of the largest int it can handle
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2625 (LONG_MAX, as defined in the system header files)
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2626 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2627
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2628
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2629 \subsection{Long Integer Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2630
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2631 \begin{ctypedesc}{PyLongObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2632 This subtype of \code{PyObject} represents a Python long integer object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2633 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2634
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2635 \begin{cvardesc}{PyTypeObject}{PyLong_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2636 This instance of \code{PyTypeObject} represents the Python long integer type.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2637 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2638
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2639 \begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2640 returns true if it's argument is a \code{PyLongObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2641 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2642
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2643 \begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2644
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2645 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2646
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2647 \begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2648
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2649 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2650
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2651 \begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2652
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2653 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2654
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2655 \begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2656
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2657 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2658
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2659 \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2660
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2661 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2662
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2663 \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2664
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2665 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2666
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2667 \begin{cfuncdesc}{PyObject *}{*PyLong_FromString}{char *, char **, int}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2668
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2669 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2670
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2671
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2672 \subsection{Floating Point Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2673
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2674 \begin{ctypedesc}{PyFloatObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2675 This subtype of \code{PyObject} represents a Python floating point object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2676 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2677
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2678 \begin{cvardesc}{PyTypeObject}{PyFloat_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2679 This instance of \code{PyTypeObject} represents the Python floating
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2680 point type.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2681 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2682
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2683 \begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2684 returns true if it's argument is a \code{PyFloatObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2685 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2686
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2687 \begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2688
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2689 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2690
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2691 \begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2692
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2693 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2694
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2695 \begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2696
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2697 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2698
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2699
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2700 \subsection{Complex Number Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2701
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2702 \begin{ctypedesc}{Py_complex}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2703 typedef struct {
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2704 double real;
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2705 double imag;
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2706 }
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2707 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2708
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2709 \begin{ctypedesc}{PyComplexObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2710 This subtype of \code{PyObject} represents a Python complex number object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2711 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2712
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2713 \begin{cvardesc}{PyTypeObject}{PyComplex_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2714 This instance of \code{PyTypeObject} represents the Python complex
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2715 number type.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2716 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2717
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2718 \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2719 returns true if it's argument is a \code{PyComplexObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2720 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2721
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2722 \begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2723
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2724 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2725
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2726 \begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2727
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2728 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2729
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2730 \begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2731
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2732 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2733
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2734 \begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2735
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2736 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2737
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2738 \begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2739
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2740 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2741
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2742 \begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2743
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2744 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2745
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2746 \begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2747
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2748 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2749
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2750 \begin{cfuncdesc}{PyObject *}{PyComplex_FromDoubles}{double real, double imag}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2751
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2752 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2753
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2754 \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2755
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2756 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2757
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2758 \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2759
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2760 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2761
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2762 \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2763
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2764 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2765
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2766
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2767
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2768 \section{Other Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2769
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2770 \subsection{File Objects}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2771
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2772 \begin{ctypedesc}{PyFileObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2773 This subtype of \code{PyObject} represents a Python file object.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2774 \end{ctypedesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2775
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2776 \begin{cvardesc}{PyTypeObject}{PyFile_Type}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2777 This instance of \code{PyTypeObject} represents the Python file type.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2778 \end{cvardesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2779
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2780 \begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2781 returns true if it's argument is a \code{PyFileObject}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2782 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2783
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2784 \begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2785 creates a new PyFileObject pointing to the file
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2786 specified in \code{name} with the mode specified in \code{mode}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2787 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2788
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2789 \begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2790 char *name, char *mode, int (*close})
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2791 creates a new PyFileObject from the already-open \code{fp}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2792 The function \code{close} will be called when the file should be closed.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2793 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2794
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2795 \begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2796 returns the file object associated with \code{p} as a \code{FILE *}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2797 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2798
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2799 \begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2800 undocumented as yet
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2801 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2802
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2803 \begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2804 returns the name of the file specified by \code{p} as a
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2805 PyStringObject
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2806 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2807
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2808 \begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2809 on systems with \code{setvbuf} only
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2810 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2811
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2812 \begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2813 same as the file object method \code{softspace}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2814 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2815
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2816 \begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2817 writes object \code{obj} to file object \code{p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2818 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2819
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2820 \begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2821 writes string \code{s} to file object \code{p}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2822 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2823
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2824
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2825 \input{api.ind} % Index -- must be last
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2826
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2827 \end{document}