Mercurial > cpython-lru_cache-weakref

annotate Doc/api/api.tex @ 7278:59d2761ba1cf legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Remove obsolete pagenumbering / pagestyle cruft.
author Fred Drake <fdrake@acm.org>
date Fri, 13 Feb 1998 07:08:56 +0000
parents 0061d3916ae4
children 8096fec722ba
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
7071
0314ecbc5f5d Added openright option the the \documentclass{} for each of the manuals.
Fred Drake <fdrake@acm.org>
parents: 7043
diff changeset
1 \documentclass[twoside,openright]{report}
7043
76eaf36040be Revise prologue and frontmatter to use latex2e (not in 2.09 compatibility
Fred Drake <fdrake@acm.org>
parents: 7023
diff changeset
2 \usepackage{myformat}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
3
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
4 \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
5
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
6 \input{boilerplate}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
7
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
8 \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
9
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
10
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
11 \begin{document}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
12
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
13 \maketitle
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
14
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
15 \input{copyright}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
16
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
17 \begin{abstract}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
18
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
19 \noindent
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
20 This manual documents the API used by \C{} (or \Cpp{}) programmers who want
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
21 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
22 ``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
23 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
24 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
25
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
26 \strong{Warning:} The current version of this document is incomplete.
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
27 I hope that it is nevertheless useful. I will continue to work on it,
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
28 and release new versions from time to time, independent from Python
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
29 source code releases.
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
30
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
31 \end{abstract}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
32
7092
8a55643e667f Removed \mytableofcontents; just use \tableofcontents.
Fred Drake <fdrake@acm.org>
parents: 7081
diff changeset
33 \tableofcontents
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
34
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
35 % 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
36 % 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
37
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
38 \chapter{Introduction}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
39
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
40 The Application Programmer's Interface to Python gives \C{} and \Cpp{}
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
41 programmers access to the Python interpreter at a variety of levels.
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
42 The API is equally usable from \Cpp{}, but for brevity it is generally
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
43 referred to as the Python/\C{} API. There are two fundamentally
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
44 different reasons for using the Python/\C{} API. The first reason is to
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
45 write ``extension modules'' for specific purposes; these are \C{} modules
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
46 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
47 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
48 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
49 Python in an application.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
50
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
51 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
52 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
53 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
54 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
55 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
56 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
57 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
58 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
59 % 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
60
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
61 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
62 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
63 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
64 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
65 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
66
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
67 \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
68
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
69 All function, type and macro definitions needed to use the Python/C
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
70 API are included in your code by the following line:
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
71
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 \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
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 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
75 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
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 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
78 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
79 \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
80 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
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 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
83 \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
84 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
85 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
86
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
87 \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
88
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
89 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
90 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
91 (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
92 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
93 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
94 and argument passing), it is only fitting that they should be
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
95 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
96 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
97 \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
98 be declared.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
99
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
100 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
101 ``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
102 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
103 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
104 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
105 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
106 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
107
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
108 \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
109
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
110 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
111 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
112 different places there are that have a reference to an object. Such a
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
113 place could be another object, or a global (or static) \C{} variable, or
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
114 a local variable in some \C{} function. When an object's reference count
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
115 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
116 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
117 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
118 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
119 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
120 ``don't do that''.)
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
121
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
122 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
123 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
124 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
125 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
126 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
127 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
128 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
129 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
130 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
131 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
132 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
133 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
134 \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
135 increment is a simple operation.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
136
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
137 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
138 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
139 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
140 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
141 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
142 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
143 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
144 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
145 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
146 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
147 temporarily. An important situation where this arises is in objects
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
148 that are passed as arguments to \C{} functions in an extension module
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
149 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
150 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
151
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
152 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
153 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
154 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
155 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
156 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
157 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
158 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
159 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
160
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
161 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
162 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
163 \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
164 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
165 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
166 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
167
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
168 \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
169
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
170 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
171 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
172 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
173 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
174 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
175 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
176 passes ownership of a reference on to its caller, the caller is said
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
177 to receive a \emph{new} reference. When no ownership is transferred,
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 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
179 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
180
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
181 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
182 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
183 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
184 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
185 \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
186 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
187 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
188 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
189 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
190 (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
191 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
192
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
193 \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
194 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
195 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
196 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
197 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
198 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
199 \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
200
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
201 Incidentally, \code{PyTuple_SetItem()} is the \emph{only} way to set
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
202 tuple items; \code{PySequence_SetItem()} and \code{PyObject_SetItem()}
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
203 refuse to do this since tuples are an immutable data type. You should
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
204 only use \code{PyTuple_SetItem()} for tuples that you are creating
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
205 yourself.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
206
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
207 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
208 \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
209 use \code{PySequence_SetItem()}; this illustrates the difference
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
210 between the two (the extra \code{Py_DECREF()} calls):
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
211
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 \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
213 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
214 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
215 x = PyInt_FromLong(1L);
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
216 PySequence_SetItem(l, 0, x); Py_DECREF(x);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
217 x = PyInt_FromLong(2L);
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
218 PySequence_SetItem(l, 1, x); Py_DECREF(x);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
219 x = PyString_FromString("three");
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
220 PySequence_SetItem(l, 2, x); Py_DECREF(x);
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
221 \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
222
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
223 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
224 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
225 creating and populating a tuple or list. There's a generic function,
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
226 \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
227 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
228 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
229 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
230
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
231 \begin{verbatim}
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
232 PyObject *t, *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
233 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
234 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
235 \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
236
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 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
238 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
239 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
240 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
241 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
242 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
243 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
244
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 \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
246 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
247 {
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 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
249 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
250 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
251 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
252 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
253 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
254 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
255 }
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 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
257 }
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 \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
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 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
261 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
262 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
263 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
264 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
265 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
266 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
267 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
268 \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
269 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
270
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 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
272 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
273 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
274 argument to the function) \emph{don't enter into it!} Thus, if you
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
275 extract an item from a list using \code{PyList_GetItem()}, you don't
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
276 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
277 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
278 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
279
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 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
281 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
282 \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
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 \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
285 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
286 {
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 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
288 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
289 PyObject *item;
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
290 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
291 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
292 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
293 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
294 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
295 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
296 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
297 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
298 return 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
299 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
300 \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
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 \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
303 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
304 {
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
305 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
306 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
307 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
308 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
309 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
310 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
311 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
312 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
313 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
314 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
315 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
316 total += PyInt_AsLong(item);
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
317 Py_DECREF(item); /* Discard reference ownership */
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
318 }
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
319 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
320 }
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 \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
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 \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
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 There are few other data types that play a significant role in
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
326 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
327 \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
328 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
329 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
330 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
331
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
332 \section{Exceptions}
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
333
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
334 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
335 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
336 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
337 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
338 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
339
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
340 For \C{} programmers, however, error checking always has to be explicit.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
341 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
342 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
343 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
344 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
345 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
346 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
347 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
348 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
349 \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
350
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
351 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
352 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
353 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
354 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
355 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
356 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
357 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
358 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
359 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
360
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 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
362 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
363 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
364 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
365 \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
366 objects represent the last exception being handled by a Python
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
367 \code{try...except} statement, while the \C{} level exception state only
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
368 exists while an exception is being passed on between \C{} functions until
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
369 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
370 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
371
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 (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
373 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
374 \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
375 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
376 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
377 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
378 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
379 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
380 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
381 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
382 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
383
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 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
385 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
386 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
387 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
388 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
389 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
390 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
391
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 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
393 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
394 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
395 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
396 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
397 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
398
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
399 \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
400 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
401 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
402 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
403 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
404 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
405 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
406 \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
407
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
408 Here is the corresponding \C{} code, in all its glory:
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
409
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 \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
411 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
412 {
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 /* 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
414 PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL;
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
415 int rv = -1; /* Return value initialized to -1 (failure) */
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
416
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
417 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
418 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
419 /* 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
420 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
421
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 /* 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
423 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
424 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
425 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
426 }
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
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
428 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
429 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
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 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
432 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
433
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
434 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
435 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
436 /* 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
437
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
438 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
439 /* 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
440
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 /* 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
442 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
443 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
444 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
445
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
446 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
447 }
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 \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
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 This example represents an endorsed use of the \code{goto} statement
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
451 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
452 \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
453 \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
454 \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
455 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
456 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
457 \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
458 initialized to \code{-1} (failure) and only set to success after
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
459 the final call made is successful.
6084
0aa62cbed9f8 Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents: 6074
diff changeset
460
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
461
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
462 \section{Embedding Python}
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
463
6653
c6c1d133677a Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents: 6480
diff changeset
464 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
465 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
466 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
467 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
468 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
469
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
470 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
471 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
472 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
473 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
474
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
475 \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
476 (\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
477 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
478 \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
479 to \code{Py_Initialize()}.
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
480
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
481 On most systems (in particular, on \UNIX{} and Windows, although the
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
482 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
483 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
484 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
485 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
486 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
487 \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
488 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
489 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
490 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
491
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
492 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
493 \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
494 \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
495 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
496 \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
497 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
498 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
499 setting \code{\$PYTHONPATH}.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
500
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
501 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
502 \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
503 \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
504 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
505 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
506 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
507 \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
508 \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
509 \file{Modules/getpath.c}).
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
510
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
511 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
512 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
513 \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
514 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
515 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
516 \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
517 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
518 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
519
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
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
521 \chapter{The Very High Level Layer}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
522
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
523 The functions in this chapter will let you execute Python source code
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
524 given in a file or a buffer, but they will not let you interact in a
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
525 more detailed way with the interpreter.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
526
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
527 \begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *, char *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
528 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
529
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
530 \begin{cfuncdesc}{int}{PyRun_SimpleString}{char *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
531 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
532
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
533 \begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *, char *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
534 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
535
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
536 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *, char *}
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
537 \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
538
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
539 \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *, char *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
540 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
541
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
542 \begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseString}{char *, int}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
543 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
544
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
545 \begin{cfuncdesc}{struct _node *}{PyParser_SimpleParseFile}{FILE *, char *, int}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
546 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
547
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
548 \begin{cfuncdesc}{PyObject *}{PyRun_String}{char *, int, PyObject *, PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
549 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
550
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
551 \begin{cfuncdesc}{PyObject *}{PyRun_File}{FILE *, char *, int, PyObject *, PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
552 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
553
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
554 \begin{cfuncdesc}{PyObject *}{Py_CompileString}{char *, char *, int}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
555 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
556
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 \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
559
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
560 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
561 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
562
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
563 \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
564 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
565 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
566 \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
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_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
570 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
571 \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
572 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
573
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
574 \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
575 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
576 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
577 \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
578 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
579
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
580 \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
581 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
582 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
583 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
584 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
585 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
586 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
587 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
588 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
589 temporary variable.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
590 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
591
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
592 \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
593 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
594 \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
595 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
596 applies.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
597 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
598
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
599 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
600 \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
601 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
602
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
603 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
604 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
605 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
606
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
607
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
608 \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
609
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
610 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
611 exceptions. It is important to understand some of the basics of
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
612 Python exception handling. It works somewhat like the \UNIX{}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
613 \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
614 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
615 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
616 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
617 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
618 (exception: the \code{PyArg_Parse*()} functions return 1 for success and
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
619 0 for failure). When a function must fail because some function it
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
620 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
621 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
622
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
623 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
624 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
625 \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
626 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
627 for each thread.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
628
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
629 % 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
630 % 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
631
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
632 \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
633 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
634 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
635 (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
636 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
637
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
638 \begin{cfuncdesc}{PyObject *}{PyErr_Occurred}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
639 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
640 \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
641 \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
642 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
643 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
644 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
645 \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
646 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
647
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
648 \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
649 \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
650 Equivalent to
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
651 \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
652 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
653 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
654
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
655 \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
656 \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
657 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
658 \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
659 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
660 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
661 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
662 set.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
663 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
664
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
665 \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
666 \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
667 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
668 \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
669 \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
670 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
671 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
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_Clear}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
675 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
676 is no effect.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
677 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
678
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
679 \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
680 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
681 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
682 \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
683 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
684 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
685 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
686 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
687 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
688
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
689 \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
690 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
691 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
692 \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
693 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
694 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
695 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
696 (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
697 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
698 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
699 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
700 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
701 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
702 temporarily.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
703 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
704
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
705 \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
706 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
707 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
708 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
709 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
710 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
711 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
712
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
713 \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
714 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
715 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
716 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
717 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
718
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
719 \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
720 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
721 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
722
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
723 \begin{cfuncdesc}{int}{PyErr_BadArgument}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
724 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
725 \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
726 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
727 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
728
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
729 \begin{cfuncdesc}{PyObject *}{PyErr_NoMemory}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
730 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
731 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
732 \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
733 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
734
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
735 \begin{cfuncdesc}{PyObject *}{PyErr_SetFromErrno}{PyObject *type}
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
736 This is a convenience function to raise an exception when a \C{} library
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
737 function has returned an error and set the \C{} variable \code{errno}.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
738 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
739 \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
740 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
741 \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
742 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
743 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
744 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
745 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
746 \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
747 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
748
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
749 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
750 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
751 \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
752 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
753 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
754 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
755
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
756 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
757 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
758 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
759 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
760 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
761 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
762 \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
763 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
764 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
765 it was previously set.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
766 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
767
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
768 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
769 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
770 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
771 \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
772 raised.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
773 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
774
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
775 \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
776 PyObject *base, PyObject *dict}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
777 \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
778 This utility function creates and returns a new exception object. The
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
779 \var{name} argument must be the name of the new exception, a \C{} string
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
780 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
781 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
782 object derived from the root for all exceptions, the built-in name
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
783 \code{Exception} (accessible in \C{} as \code{PyExc_Exception}). In this
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
784 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
785 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
786 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
787 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
788 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
789 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
790 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
791 \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
792 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
793 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
794 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
795
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
796
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
797 \section{Standard Exceptions}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
798
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
799 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
800 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
801 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
802 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
803 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
804 \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
805 \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
806 \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
807 \code{PyExc_LookupError},
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
808 \code{PyExc_AssertionError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
809 \code{PyExc_AttributeError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
810 \code{PyExc_EOFError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
811 \code{PyExc_FloatingPointError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
812 \code{PyExc_IOError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
813 \code{PyExc_ImportError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
814 \code{PyExc_IndexError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
815 \code{PyExc_KeyError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
816 \code{PyExc_KeyboardInterrupt},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
817 \code{PyExc_MemoryError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
818 \code{PyExc_NameError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
819 \code{PyExc_OverflowError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
820 \code{PyExc_RuntimeError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
821 \code{PyExc_SyntaxError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
822 \code{PyExc_SystemError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
823 \code{PyExc_SystemExit},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
824 \code{PyExc_TypeError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
825 \code{PyExc_ValueError},
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
826 \code{PyExc_ZeroDivisionError}.
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
827
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
828
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
829 \chapter{Utilities}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
830
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
831 The functions in this chapter perform various utility tasks, such as
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
832 parsing function arguments and constructing Python values from \C{}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
833 values.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
834
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
835 \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
836
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
837 \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
838 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
839 \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
840 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
841 \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
842 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
843 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
844 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
845
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
846 \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
847 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
848 The result is encoded in the same way as the timestamp returned by
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
849 the standard \C{} library function \code{time()}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
850 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
851
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
852
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
853 \section{Process Control}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
854
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
855 \begin{cfuncdesc}{void}{Py_FatalError}{char *message}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
856 Print a fatal error message and kill the process. No cleanup is
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
857 performed. This function should only be invoked when a condition is
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
858 detected that would make it dangerous to continue using the Python
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
859 interpreter; e.g., when the object administration appears to be
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
860 corrupted. On \UNIX{}, the standard \C{} library function \code{abort()} is
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
861 called which will attempt to produce a \file{core} file.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
862 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
863
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
864 \begin{cfuncdesc}{void}{Py_Exit}{int status}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
865 Exit the current process. This calls \code{Py_Finalize()} and then
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
866 calls the standard \C{} library function \code{exit(\var{status})}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
867 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
868
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
869 \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
870 Register a cleanup function to be called by \cfunction{Py_Finalize()}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
871 The cleanup function will be called with no arguments and should
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
872 return no value. At most 32 cleanup functions can be registered.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
873 When the registration is successful, \cfunction{Py_AtExit()} returns
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
874 \code{0}; on failure, it returns \code{-1}. The cleanup function
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
875 registered last is called first. Each cleanup function will be called
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
876 at most once. Since Python's internal finallization will have
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
877 completed before the cleanup function, no Python APIs should be called
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
878 by \var{func}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
879 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
880
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
881
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
882 \section{Importing Modules}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
883
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
884 \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
885 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
886 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
887 \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
888 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
889 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
890 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
891 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
892 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
893 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
894 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
895 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
896 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
897 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
898
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
899 \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
900 \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
901 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
902 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
903 \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
904
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
905 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
906 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
907 (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
908 \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
909 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
910 \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
911 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
912
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
913 \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
914 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
915 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
916 \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
917 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
918 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
919 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
920
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
921 \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
922 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
923 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
924 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
925 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
926 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
927 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
928
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
929 \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
930 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
931 \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
932 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
933 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
934 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
935 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
936 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
937 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
938
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
939 \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
940 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
941 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
942 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
943 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
944 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
945 (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
946 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
947
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
948 \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
949 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
950 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
951 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
952 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
953
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
954 \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
955 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
956 (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
957 variable.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
958 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
959
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
960 \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
961 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
962 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
963
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
964 \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
965 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
966 \end{cfuncdesc}
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{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
969 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
970 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
971
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
972 \begin{cfuncdesc}{extern PyObject *}{_PyImport_FindExtension}{char *, char *}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
973 For internal use only.
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
974 \end{cfuncdesc}
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
975
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
976 \begin{cfuncdesc}{extern PyObject *}{_PyImport_FixupExtension}{char *, char *}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
977 For internal use only.
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
978 \end{cfuncdesc}
6382
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
979
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
980 \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
981 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
982 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
983 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
984 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
985 (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
986 already imported.)
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
987 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
988
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
989 \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
990 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
991 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
992 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
993 \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
994 struct _frozen {
6480
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
995 char *name;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
996 unsigned char *code;
727b52031212 struct _frozen:
Fred Drake <fdrake@acm.org>
parents: 6417
diff changeset
997 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
998 };
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
999 \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
1000 \end{ctypedesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1001
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1002 \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
1003 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
1004 _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
1005 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
1006 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
1007 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
1008 \end{cvardesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1009
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
1010
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1011 \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
1012
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1013 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
1014 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
1015 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
1016 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
1017
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1018 \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
1019
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1020 \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
1021 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
1022 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
1023 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
1024 \end{cfuncdesc}
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 \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
1027 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
1028 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
1029 \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
1030 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
1031 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1032
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1033 \begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, char *attr_name}
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
1034 Retrieve an attribute 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
1035 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
1036 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
1037 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1038
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1039
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1040 \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
1041 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
1042 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
1043 \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
1044 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
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}{PyObject*}{PyObject_GetAttr}{PyObject *o, PyObject *attr_name}
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
1049 Retrieve an attribute 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
1050 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
1051 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
1052 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1053
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 \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
1056 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
1057 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
1058 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
1059 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1060
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 \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
1063 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
1064 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_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
1071 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
1072 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
1073 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
1074 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1075
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 \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
1078 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
1079 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
1080 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
1081 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1082
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 \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
1085 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
1086 \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
1087 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
1088 -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
1089 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
1090 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1093 \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
1094 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
1095 \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
1096 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
1097 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
1098 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
1099 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1102 \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
1103 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
1104 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
1105 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
1106 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
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_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
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{str(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{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
1115 statement.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1116 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1119 \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
1120 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
1121 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
1122 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
1123 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1124
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 \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
1127 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
1128 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
1129 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
1130 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
1131 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
1132 \end{cfuncdesc}
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_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
1135 Call a callable Python object \code{callable_object}, with a
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
1136 variable number of \C{} arguments. The \C{} arguments are described
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1137 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
1138 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
1139 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
1140 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
1141 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1142
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1143
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1144 \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
1145 Call the method named \code{m} of object \code{o} with a variable number of
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
1146 C arguments. The \C{} arguments are described by a mkvalue
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1147 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
1148 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
1149 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
1150 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
1151 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
1152 "\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
1153 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
1154 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1155
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1156
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1157 \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
1158 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
1159 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
1160 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
1161 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1162
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 \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
1165 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
1166 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
1167 \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
1168 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
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}{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
1173 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
1174 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
1175 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
1176 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1177
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1178 \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
1179 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
1180 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
1181 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
1182 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
1183 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1184
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}{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
1187 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
1188 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
1189 \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
1190 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1191
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 \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
1194 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
1195 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
1196 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
1197 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1198
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 \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
1201 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
1202 on failure.
6040
1a43699108a6 Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents: 5588
diff changeset
1203 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
1204 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1205
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 \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
1208
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1209 \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
1210 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
1211 false otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1212 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
1213 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1216 \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
1217 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
1218 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
1219 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1220
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1221
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1222 \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
1223 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
1224 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
1225 \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
1226 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1227
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1228
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1229 \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
1230 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
1231 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
1232 \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
1233 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1234
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 \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
1237 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
1238 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
1239 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1240
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1241
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1242 \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
1243 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
1244 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
1245 \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
1246 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1247
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 \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
1250 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
1251 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
1252 \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
1253 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1254
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 \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
1257 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
1258 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
1259 \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
1260 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1261
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 \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
1264 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
1265 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
1266 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1267
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1268
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1269 \begin{cfuncdesc}{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
1270 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
1271 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
1272 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1273
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1274
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1275 \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
1276 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
1277 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
1278 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1279
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1280
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1281 \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
1282 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
1283 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
1284 \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
1285 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1286
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 \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
1289 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
1290 \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
1291 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
1292 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1293
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 \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
1296 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
1297 \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
1298 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
1299 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1300
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1301
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1302 \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
1303 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
1304 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
1305 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
1306 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1307
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 \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
1310 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
1311 \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
1312 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
1313 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1314
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1315 \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
1316 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
1317 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
1318 \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
1319 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1320
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1321
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1322 \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
1323 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
1324 \code{PyObject*}.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1325
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1326 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
1327 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
1328 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
1329 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
1330 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
1331 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
1332 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
1333 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
1334 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
1335 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1336
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1337
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1338 \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
1339 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
1340 \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
1341 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
1342 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1343
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 \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
1346 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
1347 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
1348 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
1349 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1350
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 \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
1353 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
1354 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
1355 \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
1356 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1357
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1358
7268
a2f4c944cb87 For sections describing the "Foo Protocol", consistently use the capitalized
Fred Drake <fdrake@acm.org>
parents: 7267
diff changeset
1359 \section{Sequence Protocol}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1360
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1361 \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
1362 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
1363 otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1364 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
1365 \end{cfuncdesc}
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1368 \begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2}
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
1369 Return the concatenation of \code{o1} and \code{o2} on success, and \NULL{} on
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1370 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
1371 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
1372 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1373
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 \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
1376 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
1377 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
1378 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
1379 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1380
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 \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
1383 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
1384 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
1385 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1386
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1387
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1388 \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
1389 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
1390 \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
1391 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
1392 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1393
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 \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
1396 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
1397 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
1398 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
1399 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1400
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1401 \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
1402 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
1403 -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
1404 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
1405 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1406
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1407 \begin{cfuncdesc}{int}{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
1408 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
1409 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
1410 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
1411 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1412
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1413 \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
1414 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
1415 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
1416 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
1417 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1418
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1419 \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
1420 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
1421 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
1422 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1423
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1424 \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
1425 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
1426 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
1427 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
1428 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
1429 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1430
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1431 \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
1432 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
1433 \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
1434 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
1435 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1436
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1437 \begin{cfuncdesc}{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
1438 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
1439 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
1440 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
1441 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1442
7268
a2f4c944cb87 For sections describing the "Foo Protocol", consistently use the capitalized
Fred Drake <fdrake@acm.org>
parents: 7267
diff changeset
1443 \section{Mapping Protocol}
5536
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}{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
1446 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
1447 otherwise.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1448 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
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
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1452 \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
1453 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
1454 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
1455 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
1456 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1457
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1458
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1459 \begin{cfuncdesc}{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
1460 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
1461 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
1462 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
1463 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1464
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1465
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1466 \begin{cfuncdesc}{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
1467 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
1468 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
1469 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
1470 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1471
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1472
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1473 \begin{cfuncdesc}{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
1474 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
1475 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
1476 \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
1477 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
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_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
1482 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}{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
1490 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
1491 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
1492 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
1493 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1494
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 \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
1497 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
1498 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
1499 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
1500 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1501
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1502
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1503 \begin{cfuncdesc}{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
1504 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
1505 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
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.items()}.
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 \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
1511 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
1512 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
1513 \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
1514 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1515
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1516
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1517 \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
1518 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
1519 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
1520 \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
1521 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1522
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1523 \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
1524 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
1525 -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
1526 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
1527 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1528
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1529
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1530 \section{Constructors}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1531
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1532 \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
1533 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
1534 file given by \code{file_name}, with a file mode given by \code{mode},
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
1535 where \code{mode} has the same semantics as the standard \C{} routine,
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1536 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
1537 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1538
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1539 \begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, char *file_name, char *mode, int close_on_del}
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
1540 Return a new file object for an already opened standard \C{}
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1541 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
1542 \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
1543 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
1544 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
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*}{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
1548 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
1549 \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
1550 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1551
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1552 \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
1553 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
1554 \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
1555 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1556
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1557 \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
1558 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
1559 failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1560 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1561
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1562 \begin{cfuncdesc}{PyObject*}{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
1563 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
1564 \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
1565 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1566
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1567 \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
1568 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
1569 \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
1570 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1571
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1572 \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
1573 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
1574 failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1575 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1576
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1577 \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
1578 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
1579 \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
1580 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1581
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1582 \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
1583 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
1584 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
1585 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1586
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1587 \begin{cfuncdesc}{PyObject*}{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
1588 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
1589 failure.
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1590 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1591
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1592
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1593 \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
1594
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1595 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
1596 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
1597 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
1598 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
1599 e.g. to check that an object is a dictionary, use
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1600 \cfunction{PyDict_Check()}. The chapter is structured like the
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1601 ``family tree'' of Python object types.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1602
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1603
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1604 \section{Fundamental Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1605
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1606 This section describes Python type objects and the singleton object
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1607 \code{None}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1608
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1609
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1610 \subsection{Type Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1611
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1612 \begin{ctypedesc}{PyTypeObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1613
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1614 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1615
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1616 \begin{cvardesc}{PyObject *}{PyType_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1617
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1618 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1619
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1620
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1621 \subsection{The None Object}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1622
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1623 \begin{cvardesc}{PyObject *}{Py_None}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1624 XXX macro
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1625 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1626
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1627
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1628 \section{Sequence Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1629
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1630 Generic operations on sequence objects were discussed in the previous
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1631 chapter; this section deals with the specific kinds of sequence
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1632 objects that are intrinsic to the Python language.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1633
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1634
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1635 \subsection{String Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1636
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1637 \begin{ctypedesc}{PyStringObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1638 This subtype of \code{PyObject} represents a Python string object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1639 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1640
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1641 \begin{cvardesc}{PyTypeObject}{PyString_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1642 This instance of \code{PyTypeObject} represents the Python string type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1643 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1644
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1645 \begin{cfuncdesc}{int}{PyString_Check}{PyObject *o}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1646
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1647 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1648
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1649 \begin{cfuncdesc}{PyObject *}{PyString_FromStringAndSize}{const char *, int}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1650
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1651 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1652
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1653 \begin{cfuncdesc}{PyObject *}{PyString_FromString}{const char *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1654
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1655 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1656
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1657 \begin{cfuncdesc}{int}{PyString_Size}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1658
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1659 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1660
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1661 \begin{cfuncdesc}{char *}{PyString_AsString}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1662
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1663 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1664
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1665 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **, PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1666
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1667 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1668
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1669 \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **, PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1670
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1671 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1672
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1673 \begin{cfuncdesc}{int}{_PyString_Resize}{PyObject **, int}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1674
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1675 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1676
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1677 \begin{cfuncdesc}{PyObject *}{PyString_Format}{PyObject *, PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1678
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1679 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1680
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1681 \begin{cfuncdesc}{void}{PyString_InternInPlace}{PyObject **}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1682
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1683 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1684
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1685 \begin{cfuncdesc}{PyObject *}{PyString_InternFromString}{const char *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1686
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1687 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1688
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1689 \begin{cfuncdesc}{char *}{PyString_AS_STRING}{PyStringObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1690
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1691 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1692
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1693 \begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyStringObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1694
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1695 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1696
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1697
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1698 \subsection{Tuple Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1699
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1700 \begin{ctypedesc}{PyTupleObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1701 This subtype of \code{PyObject} represents a Python tuple object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1702 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1703
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1704 \begin{cvardesc}{PyTypeObject}{PyTuple_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1705 This instance of \code{PyTypeObject} represents the Python tuple type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1706 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1707
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1708 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1709 Return true if the argument is a tuple object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1710 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1711
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1712 \begin{cfuncdesc}{PyTupleObject *}{PyTuple_New}{int s}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1713 Return a new tuple object of size \code{s}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1714 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1715
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1716 \begin{cfuncdesc}{int}{PyTuple_Size}{PyTupleObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1717 akes a pointer to a tuple object, and returns the size
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1718 of that tuple.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1719 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1720
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1721 \begin{cfuncdesc}{PyObject *}{PyTuple_GetItem}{PyTupleObject *p, int pos}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1722 returns the object at position \code{pos} in the tuple pointed
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1723 to by \code{p}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1724 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1725
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1726 \begin{cfuncdesc}{PyObject *}{PyTuple_GET_ITEM}{PyTupleObject *p, int pos}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1727 does the same, but does no checking of it's
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1728 arguments.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1729 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1730
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1731 \begin{cfuncdesc}{PyTupleObject *}{PyTuple_GetSlice}{PyTupleObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1732 int low,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1733 int high}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1734 takes a slice of the tuple pointed to by \code{p} from
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1735 \code{low} to \code{high} and returns it as a new tuple.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1736 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1737
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1738 \begin{cfuncdesc}{int}{PyTuple_SetItem}{PyTupleObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1739 int pos,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1740 PyObject *o}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1741 inserts a reference to object \code{o} at position \code{pos} of
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1742 the tuple pointed to by \code{p}. It returns 0 on success.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1743 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1744
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1745 \begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyTupleObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1746 int pos,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1747 PyObject *o}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1748
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1749 does the same, but does no error checking, and
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1750 should \emph{only} be used to fill in brand new tuples.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1751 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1752
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1753 \begin{cfuncdesc}{PyTupleObject *}{_PyTuple_Resize}{PyTupleObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1754 int new,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1755 int last_is_sticky}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1756 can be used to resize a tuple. Because tuples are
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1757 \emph{supposed} to be immutable, this should only be used if there is only
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1758 one module referencing the object. Do \emph{not} use this if the tuple may
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1759 already be known to some other part of the code. \code{last_is_sticky} is
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1760 a flag - if set, the tuple will grow or shrink at the front, otherwise
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1761 it will grow or shrink at the end. Think of this as destroying the old
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1762 tuple and creating a new one, only more efficiently.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1763 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1764
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1765
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1766 \subsection{List Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1767
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1768 \begin{ctypedesc}{PyListObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1769 This subtype of \code{PyObject} represents a Python list object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1770 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1771
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1772 \begin{cvardesc}{PyTypeObject}{PyList_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1773 This instance of \code{PyTypeObject} represents the Python list type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1774 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1775
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1776 \begin{cfuncdesc}{int}{PyList_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1777 returns true if it's argument is a \code{PyListObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1778 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1779
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1780 \begin{cfuncdesc}{PyObject *}{PyList_New}{int size}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1781
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1782 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1783
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1784 \begin{cfuncdesc}{int}{PyList_Size}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1785
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1786 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1787
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1788 \begin{cfuncdesc}{PyObject *}{PyList_GetItem}{PyObject *, int}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1789
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1790 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1791
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1792 \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *, int, PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1793
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1794 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1795
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1796 \begin{cfuncdesc}{int}{PyList_Insert}{PyObject *, int, PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1797
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1798 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1799
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1800 \begin{cfuncdesc}{int}{PyList_Append}{PyObject *, PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1801
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1802 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1803
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1804 \begin{cfuncdesc}{PyObject *}{PyList_GetSlice}{PyObject *, int, int}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1805
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1806 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1807
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1808 \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *, int, int, PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1809
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1810 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1811
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1812 \begin{cfuncdesc}{int}{PyList_Sort}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1813
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1814 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1815
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1816 \begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1817
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1818 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1819
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1820 \begin{cfuncdesc}{PyObject *}{PyList_AsTuple}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1821
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1822 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1823
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1824 \begin{cfuncdesc}{PyObject *}{PyList_GET_ITEM}{PyObject *list, int i}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1825
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1826 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1827
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1828 \begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1829
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1830 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1831
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1832
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1833 \section{Mapping Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1834
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1835 \subsection{Dictionary Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1836
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1837 \begin{ctypedesc}{PyDictObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1838 This subtype of \code{PyObject} represents a Python dictionary object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1839 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1840
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1841 \begin{cvardesc}{PyTypeObject}{PyDict_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1842 This instance of \code{PyTypeObject} represents the Python dictionary type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1843 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1844
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1845 \begin{cfuncdesc}{int}{PyDict_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1846 returns true if it's argument is a PyDictObject
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1847 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1848
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1849 \begin{cfuncdesc}{PyDictObject *}{PyDict_New}{}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1850 returns a new empty dictionary.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1851 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1852
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1853 \begin{cfuncdesc}{void}{PyDict_Clear}{PyDictObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1854 empties an existing dictionary and deletes it.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1855 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1856
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1857 \begin{cfuncdesc}{int}{PyDict_SetItem}{PyDictObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1858 PyObject *key,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1859 PyObject *val}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1860 inserts \code{value} into the dictionary with a key of
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1861 \code{key}. Both \code{key} and \code{value} should be PyObjects, and \code{key} should
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1862 be hashable.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1863 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1864
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1865 \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyDictObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1866 char *key,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1867 PyObject *val}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1868 inserts \code{value} into the dictionary using \code{key}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1869 as a key. \code{key} should be a char *
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1870 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1871
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1872 \begin{cfuncdesc}{int}{PyDict_DelItem}{PyDictObject *p, PyObject *key}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1873 removes the entry in dictionary \code{p} with key \code{key}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1874 \code{key} is a PyObject.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1875 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1876
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1877 \begin{cfuncdesc}{int}{PyDict_DelItemString}{PyDictObject *p, char *key}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1878 removes the entry in dictionary \code{p} which has a key
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1879 specified by the \code{char *}\code{key}.
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1880 \end{cfuncdesc}
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
1881
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1882 \begin{cfuncdesc}{PyObject *}{PyDict_GetItem}{PyDictObject *p, PyObject *key}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1883 returns the object from dictionary \code{p} which has a key
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1884 \code{key}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1885 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1886
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1887 \begin{cfuncdesc}{PyObject *}{PyDict_GetItemString}{PyDictObject *p, char *key}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1888 does the same, but \code{key} is specified as a
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1889 \code{char *}, rather than a \code{PyObject *}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1890 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1891
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1892 \begin{cfuncdesc}{PyListObject *}{PyDict_Items}{PyDictObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1893 returns a PyListObject containing all the items
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1894 from the dictionary, as in the mapping method \code{items()} (see the Reference
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1895 Guide)
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1896 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1897
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1898 \begin{cfuncdesc}{PyListObject *}{PyDict_Keys}{PyDictObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1899 returns a PyListObject containing all the keys
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1900 from the dictionary, as in the mapping method \code{keys()} (see the Reference Guide)
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1901 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1902
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1903 \begin{cfuncdesc}{PyListObject *}{PyDict_Values}{PyDictObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1904 returns a PyListObject containing all the values
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1905 from the dictionary, as in the mapping method \code{values()} (see the Reference Guide)
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1906 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1907
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1908 \begin{cfuncdesc}{int}{PyDict_Size}{PyDictObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1909 returns the number of items in the dictionary.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1910 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1911
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1912 \begin{cfuncdesc}{int}{PyDict_Next}{PyDictObject *p,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1913 int ppos,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1914 PyObject **pkey,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1915 PyObject **pvalue}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1916
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1917 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1918
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1919
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1920 \section{Numeric Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1921
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1922 \subsection{Plain Integer Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1923
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1924 \begin{ctypedesc}{PyIntObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1925 This subtype of \code{PyObject} represents a Python integer object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1926 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1927
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1928 \begin{cvardesc}{PyTypeObject}{PyInt_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1929 This instance of \code{PyTypeObject} represents the Python plain
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1930 integer type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1931 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1932
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1933 \begin{cfuncdesc}{int}{PyInt_Check}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1934
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1935 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1936
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1937 \begin{cfuncdesc}{PyIntObject *}{PyInt_FromLong}{long ival}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1938 creates a new integer object with a value of \code{ival}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1939
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1940 The current implementation keeps an array of integer objects for all
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1941 integers between -1 and 100, when you create an int in that range you
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1942 actually just get back a reference to the existing object. So it should
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1943 be possible to change the value of 1. I suspect the behaviour of python
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1944 in this case is undefined. :-)
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1945 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1946
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1947 \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyIntObject *io}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1948 returns the value of the object \code{io}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1949 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1950
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1951 \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1952 will first attempt to cast the object to a PyIntObject, if
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1953 it is not already one, and the return it's value.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1954 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1955
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1956 \begin{cfuncdesc}{long}{PyInt_GetMax}{}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1957 returns the systems idea of the largest int it can handle
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1958 (LONG_MAX, as defined in the system header files)
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1959 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1960
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1961
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1962 \subsection{Long Integer Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1963
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1964 \begin{ctypedesc}{PyLongObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1965 This subtype of \code{PyObject} represents a Python long integer object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1966 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1967
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1968 \begin{cvardesc}{PyTypeObject}{PyLong_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1969 This instance of \code{PyTypeObject} represents the Python long integer type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1970 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1971
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1972 \begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1973 returns true if it's argument is a \code{PyLongObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1974 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1975
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1976 \begin{cfuncdesc}{PyObject *}{PyLong_FromLong}{long}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1977
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1978 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1979
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1980 \begin{cfuncdesc}{PyObject *}{PyLong_FromUnsignedLong}{unsigned long}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1981
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1982 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1983
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1984 \begin{cfuncdesc}{PyObject *}{PyLong_FromDouble}{double}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1985
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1986 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1987
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1988 \begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1989
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1990 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1991
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1992 \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject }
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1993
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1994 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1995
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1996 \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1997
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1998 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
1999
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2000 \begin{cfuncdesc}{PyObject *}{PyLong_FromString}{char *, char **, int}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2001
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2002 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2003
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2004
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2005 \subsection{Floating Point Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2006
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2007 \begin{ctypedesc}{PyFloatObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2008 This subtype of \code{PyObject} represents a Python floating point object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2009 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2010
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2011 \begin{cvardesc}{PyTypeObject}{PyFloat_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2012 This instance of \code{PyTypeObject} represents the Python floating
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2013 point type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2014 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2015
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2016 \begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2017 returns true if it's argument is a \code{PyFloatObject}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2018 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2019
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2020 \begin{cfuncdesc}{PyObject *}{PyFloat_FromDouble}{double}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2021
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2022 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2023
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2024 \begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2025
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2026 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2027
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2028 \begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyFloatObject *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2029
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2030 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2031
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2032
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2033 \subsection{Complex Number Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2034
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2035 \begin{ctypedesc}{Py_complex}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2036 typedef struct {
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2037 double real;
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2038 double imag;
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2039 }
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2040 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2041
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2042 \begin{ctypedesc}{PyComplexObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2043 This subtype of \code{PyObject} represents a Python complex number object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2044 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2045
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2046 \begin{cvardesc}{PyTypeObject}{PyComplex_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2047 This instance of \code{PyTypeObject} represents the Python complex
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2048 number type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2049 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2050
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2051 \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2052 returns true if it's argument is a \code{PyComplexObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2053 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2054
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2055 \begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex, Py_complex}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2056
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2057 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2058
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2059 \begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex, Py_complex}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2060
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2061 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2062
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2063 \begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2064
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2065 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2066
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2067 \begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex, Py_complex}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2068
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2069 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2070
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2071 \begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex, Py_complex}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2072
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2073 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2074
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2075 \begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex, Py_complex}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2076
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2077 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2078
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2079 \begin{cfuncdesc}{PyObject *}{PyComplex_FromCComplex}{Py_complex}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2080
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2081 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2082
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2083 \begin{cfuncdesc}{PyObject *}{PyComplex_FromDoubles}{double real, double imag}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2084
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2085 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2086
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2087 \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2088
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2089 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2090
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2091 \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2092
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2093 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2094
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2095 \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2096
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2097 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2098
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2099
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2100
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2101 \section{Other Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2102
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2103 \subsection{File Objects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2104
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2105 \begin{ctypedesc}{PyFileObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2106 This subtype of \code{PyObject} represents a Python file object.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2107 \end{ctypedesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2108
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2109 \begin{cvardesc}{PyTypeObject}{PyFile_Type}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2110 This instance of \code{PyTypeObject} represents the Python file type.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2111 \end{cvardesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2112
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2113 \begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2114 returns true if it's argument is a \code{PyFileObject}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2115 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2116
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2117 \begin{cfuncdesc}{PyObject *}{PyFile_FromString}{char *name, char *mode}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2118 creates a new PyFileObject pointing to the file
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2119 specified in \code{name} with the mode specified in \code{mode}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2120 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2121
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2122 \begin{cfuncdesc}{PyObject *}{PyFile_FromFile}{FILE *fp,
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2123 char *name, char *mode, int (*close})
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2124 creates a new PyFileObject from the already-open \code{fp}.
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2125 The function \code{close} will be called when the file should be closed.
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2126 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2127
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2128 \begin{cfuncdesc}{FILE *}{PyFile_AsFile}{PyFileObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2129 returns the file object associated with \code{p} as a \code{FILE *}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2130 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2131
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2132 \begin{cfuncdesc}{PyStringObject *}{PyFile_GetLine}{PyObject *p, int n}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2133 undocumented as yet
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2134 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2135
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2136 \begin{cfuncdesc}{PyStringObject *}{PyFile_Name}{PyObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2137 returns the name of the file specified by \code{p} as a
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2138 PyStringObject
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2139 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2140
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2141 \begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2142 on systems with \code{setvbuf} only
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2143 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2144
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2145 \begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyFileObject *p, int newflag}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2146 same as the file object method \code{softspace}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2147 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2148
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2149 \begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2150 writes object \code{obj} to file object \code{p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2151 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2152
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2153 \begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2154 writes string \code{s} to file object \code{p}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2155 \end{cfuncdesc}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2156
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2157
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2158 \subsection{CObjects}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2159
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2160 XXX
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2161
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2162
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2163 \chapter{Initialization, Finalization, and Threads}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2164
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2165 \begin{cfuncdesc}{void}{Py_Initialize}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2166 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
2167 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
2168 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
2169 \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
2170 \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
2171 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
2172 \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
2173 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
2174 \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
2175 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
2176 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
2177 initialization fails.
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
2178 \end{cfuncdesc}
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
2179
16cd39805fd5 Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents: 6126
diff changeset
2180 \begin{cfuncdesc}{int}{Py_IsInitialized}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2181 \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
2182 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
2183 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
2184 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
2185 again.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2186 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2187
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2188 \begin{cfuncdesc}{void}{Py_Finalize}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2189 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2190 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
2191 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
2192 \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
2193 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
2194 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
2195 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
2196 \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
2197 during finalization are ignored.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2198
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2199 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
2200 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
2201 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
2202 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
2203 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
2204 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
2205 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
2206
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2207 \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
2208 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
2209 (\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
2210 (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
2211 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
2212 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
2213 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
2214 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
2215 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
2216 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
2217 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
2218 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2219
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2220 \begin{cfuncdesc}{PyThreadState *}{Py_NewInterpreter}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2221 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2222 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
2223 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
2224 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
2225 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
2226 \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
2227 (\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
2228 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
2229 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
2230 \code{sys.stdout} and \code{sys.stderr} (however these refer to the
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
2231 same underlying \code{FILE} structures in the \C{} library).
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2232
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2233 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
2234 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
2235 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
2236 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
2237 \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
2238 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
2239 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
2240 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
2241 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
2242 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
2243
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2244 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
2245 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
2246 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
2247 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
2248 (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
2249 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
2250 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
2251 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
2252 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
2253 \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
2254 function \emph{is} called again.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2255
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2256 \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
2257 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
2258 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
2259 \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
2260 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
2261 (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
2262 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
2263 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
2264 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
2265 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
2266 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
2267 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
2268 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
2269 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
2270 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
2271 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2272
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2273 \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
2274 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2275 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
2276 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
2277 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
2278 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
2279 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
2280 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
2281 \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
2282 been explicitly destroyed at that point.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2283 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2284
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2285 \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
2286 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2287 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
2288 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
2289 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
2290 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
2291 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
2292 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
2293 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
2294 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
2295 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
2296 the contents of this storage.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2297 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2298
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2299 \begin{cfuncdesc}{char *}{Py_GetProgramName}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2300 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
2301 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
2302 should not modify its value.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2303 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2304
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2305 \begin{cfuncdesc}{char *}{Py_GetPrefix}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2306 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
2307 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
2308 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
2309 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
2310 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
2311 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
2312 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
2313 \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
2314 \code{configure} script at build time. The value is available to
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
2315 Python code as \code{sys.prefix}. It is only useful on \UNIX{}. See
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2316 also the next function.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2317 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2318
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2319 \begin{cfuncdesc}{char *}{Py_GetExecPrefix}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2320 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
2321 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
2322 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
2323 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
2324 \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
2325 \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
2326 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
2327 \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
2328 \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
2329 time. The value is available to Python code as
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
2330 \code{sys.exec_prefix}. It is only useful on \UNIX{}.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2331
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2332 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
2333 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
2334 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
2335 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
2336 \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
2337 installed in \code{"/usr/local"}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2338
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2339 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
2340 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
2341 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
2342 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
2343 Linux are yet another platform. Different major revisions of the same
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
2344 operating system generally also form different platforms. Non-\UNIX{}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2345 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
2346 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
2347 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
2348 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
2349 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
2350
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2351 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
2352 \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
2353 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
2354 platform.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2355 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2356
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2357 \begin{cfuncdesc}{char *}{Py_GetProgramFullPath}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2358 \strong{(NEW in 1.5a3!)}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2359 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
2360 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
2361 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
2362 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
2363 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
2364 \code{sys.executable}.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2365 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2366
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2367 \begin{cfuncdesc}{char *}{Py_GetPath}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2368 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
2369 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
2370 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
2371 directory names separated by a platform dependent delimiter character.
7271
0061d3916ae4 "ASCII" --> "\ASCII{}"
Fred Drake <fdrake@acm.org>
parents: 7269
diff changeset
2372 The delimiter character is \code{':'} on \UNIX{}, \code{';'} on
0061d3916ae4 "ASCII" --> "\ASCII{}"
Fred Drake <fdrake@acm.org>
parents: 7269
diff changeset
2373 DOS/Windows, and \code{'\\n'} (the \ASCII{} newline character) on
0061d3916ae4 "ASCII" --> "\ASCII{}"
Fred Drake <fdrake@acm.org>
parents: 7269
diff changeset
2374 Macintosh. The returned string points into static storage; the caller
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2375 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
2376 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
2377 future search path for loaded modules.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2378
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2379 % XXX should give the exact rules
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2380 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2381
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2382 \begin{cfuncdesc}{const char *}{Py_GetVersion}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2383 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
2384 looks something like
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2385
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
2386 \begin{verbatim}
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
2387 "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
2388 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2389
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2390 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
2391 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
2392 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
2393 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
2394 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
2395 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2396
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2397 \begin{cfuncdesc}{const char *}{Py_GetPlatform}{}
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
2398 Return the platform identifier for the current platform. On \UNIX{},
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2399 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
2400 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
2401 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
2402 \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
2403 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
2404 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
2405 Python code as \code{sys.platform}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2406 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2407
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2408 \begin{cfuncdesc}{const char *}{Py_GetCopyright}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2409 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
2410 for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2411
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2412 \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
2413
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2414 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
2415 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
2416 \code{sys.copyright}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2417 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2418
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2419 \begin{cfuncdesc}{const char *}{Py_GetCompiler}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2420 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
2421 version, in square brackets, for example
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2422
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2423 \code{"[GCC 2.7.2.2]"}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2424
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2425 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
2426 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
2427 the variable \code{sys.version}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2428 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2429
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2430 \begin{cfuncdesc}{const char *}{Py_GetBuildInfo}{}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2431 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
2432 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
2433
6074
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
2434 \begin{verbatim}
5e5e54a6dba6 Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents: 6041
diff changeset
2435 "#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
2436 \end{verbatim}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2437
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2438 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
2439 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
2440 the variable \code{sys.version}.
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2441 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2442
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2443 \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
2444 % XXX
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2445 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2446
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2447 % 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
2448
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2449 \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
2450
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2451 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
2452 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
2453 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
2454 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
2455 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
2456 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
2457 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
2458
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2459 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
2460 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
2461 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
2462 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
2463 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
2464 \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
2465 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
2466 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
2467 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
2468
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2469 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
2470 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
2471 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
2472 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
2473 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
2474 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
2475 last raised in the current thread.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2476
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2477 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
2478 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
2479 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
2480 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
2481 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
2482
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2483 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
2484 interpreter lock has the following simple structure:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2485
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
2486 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2487 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
2488 Release the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2489 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2490 Reacquire the interpreter lock.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2491 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
2492 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2493
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2494 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
2495
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
2496 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2497 Py_BEGIN_ALLOW_THREADS
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2498 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2499 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
2500 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2501
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2502 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
2503 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
2504 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
2505 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
2506 manipulations.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2507
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2508 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
2509 following code:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2510
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
2511 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2512 {
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2513 PyThreadState *_save;
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2514 _save = PyEval_SaveThread();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2515 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2516 PyEval_RestoreThread(_save);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2517 }
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
2518 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2519
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2520 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
2521 as follows:
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2522
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
2523 \begin{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2524 {
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2525 PyThreadState *_save;
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2526 _save = PyThreadState_Swap(NULL);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2527 PyEval_ReleaseLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2528 ...Do some blocking I/O operation...
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2529 PyEval_AcquireLock();
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2530 PyThreadState_Swap(_save);
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2531 }
6417
4491f84ac223 Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents: 6390
diff changeset
2532 \end{verbatim}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2533
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2534 There are some subtle differences; in particular,
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2535 \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
2536 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
2537 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
2538 is disabled, \code{PyEval_SaveThread()} and
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2539 \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
2540 \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
2541 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
2542 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
2543 that was compiled with disabled thread support.)
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2544
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2545 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
2546 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
2547 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
2548 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
2549 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
2550 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
2551 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
2552
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2553 Why am I going on with so much detail about this? Because when
7081
0baa2ab42ee9 Consistency:
Fred Drake <fdrake@acm.org>
parents: 7071
diff changeset
2554 threads are created from \C{}, they don't have the global interpreter
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2555 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
2556 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
2557 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
2558 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
2559 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
2560 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
2561 structure.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2562
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2563 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
2564 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
2565 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
2566 interpreter, for example the module administration
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2567 (\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
2568 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
2569 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
2570 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
2571 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
2572 thread after Python is initialized).
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2573
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2574 XXX More?
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2575
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2576 \begin{ctypedesc}{PyInterpreterState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2577 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2578 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
2579 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
2580 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
2581 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
2582
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2583 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
2584 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
2585 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
2586 regardless of to which interpreter they belong.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2587 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2588
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2589 \begin{ctypedesc}{PyThreadState}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2590 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2591 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
2592 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
2593 to this thread's interpreter state.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2594 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2595
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2596 \begin{cfuncdesc}{void}{PyEval_InitThreads}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2597 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
2598 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
2599 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
2600 \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
2601 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
2602
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2603 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
2604 this function before calling \code{Py_Initialize()}.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2605
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2606 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
2607 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
2608 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
2609 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
2610 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
2611 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
2612 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
2613 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
2614 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
2615 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
2616 that it has acquired it.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2617
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2618 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
2619 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
2620
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2621 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
2622 compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2623 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2624
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2625 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2626 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2627 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
2628 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
2629 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
2630 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2631 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2632
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2633 \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2634 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2635 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
2636 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
2637 disabled at
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2638 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2639 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2640
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2641 \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
2642 \strong{(NEW in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2643 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
2644 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
2645 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
2646 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
2647 is disabled at
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2648 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2649 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2650
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2651 \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
2652 \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
2653 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
2654 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
2655 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
2656 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
2657 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
2658 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
2659 compile time.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2660 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2661
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2662 \begin{cfuncdesc}{PyThreadState *}{PyEval_SaveThread}{}
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2663 \strong{(Different return type in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2664 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
2665 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
2666 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
2667 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
2668 (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
2669 compile time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2670 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2671
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2672 \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2673 \strong{(Different argument type in 1.5a3!)}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2674 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
2675 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
2676 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
2677 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
2678 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
2679 time.)
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2680 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2681
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2682 % 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
2683 \begin{ctypedesc}{Py_BEGIN_ALLOW_THREADS}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2684 This macro expands to
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2685 \code{\{ PyThreadState *_save; _save = PyEval_SaveThread();}.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2686 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
2687 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
2688 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
2689 disabled at compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2690 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2691
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2692 \begin{ctypedesc}{Py_END_ALLOW_THREADS}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2693 This macro expands to
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2694 \code{PyEval_RestoreThread(_save); \} }.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2695 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
2696 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
2697 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
2698 disabled at compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2699 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2700
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2701 \begin{ctypedesc}{Py_BEGIN_BLOCK_THREADS}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2702 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
2703 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
2704 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
2705 time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2706 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2707
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2708 \begin{ctypedesc}{Py_BEGIN_UNBLOCK_THREADS}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2709 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
2710 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
2711 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
2712 disabled at compile time.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2713 \end{ctypedesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2714
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2715 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
2716 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
2717 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
2718
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2719 \begin{cfuncdesc}{PyInterpreterState *}{PyInterpreterState_New}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2720 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
2721 held.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2722 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2723
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2724 \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2725 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
2726 lock must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2727 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2728
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2729 \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2730 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
2731 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
2732 call to \code{PyInterpreterState_Clear()}.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2733 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2734
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2735 \begin{cfuncdesc}{PyThreadState *}{PyThreadState_New}{PyInterpreterState *interp}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2736 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
2737 object. The interpreter lock must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2738 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2739
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2740 \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2741 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
2742 must be held.
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2743 \end{cfuncdesc}
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2744
6390
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2745 \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2746 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
2747 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
2748 call to \code{PyThreadState_Clear()}.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2749 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2750
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2751 \begin{cfuncdesc}{PyThreadState *}{PyThreadState_Get}{}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2752 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
2753 When the current thread state is \NULL{}, this issues a fatal
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
2754 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
2755 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2756
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2757 \begin{cfuncdesc}{PyThreadState *}{PyThreadState_Swap}{PyThreadState *tstate}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2758 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
2759 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
2760 must be held.
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2761 \end{cfuncdesc}
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2762
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2763
a2df3c9e5f43 Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents: 6382
diff changeset
2764 \section{Defining New Object Types}
6041
a9e1ea80ea3f Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents: 6040
diff changeset
2765
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2766 XXX To be done:
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 PyObject, PyVarObject
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 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
2771
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2772 Typedefs:
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2773 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
2774 intintargfunc, intobjargproc, intintobjargproc, objobjargproc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2775 getreadbufferproc, getwritebufferproc, getsegcountproc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2776 destructor, printfunc, getattrfunc, getattrofunc, setattrfunc,
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2777 setattrofunc, cmpfunc, reprfunc, hashfunc
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2778
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2779 PyNumberMethods
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2780
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2781 PySequenceMethods
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2782
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2783 PyMappingMethods
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2784
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2785 PyBufferProcs
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2786
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2787 PyTypeObject
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 DL_IMPORT
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2790
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2791 PyType_Type
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2792
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2793 Py*_Check
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 Py_None, _Py_NoneStruct
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2796
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2797 _PyObject_New, _PyObject_NewVar
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 PyObject_NEW, PyObject_NEW_VAR
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2800
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2801
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2802 \chapter{Defining New Object Types}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2803
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2804 \begin{cfuncdesc}{PyObject *}{_PyObject_New}{PyTypeObject *type}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2805 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2806
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2807 \begin{cfuncdesc}{PyObject *}{_PyObject_NewVar}{PyTypeObject *type, int size}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2808 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2809
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2810 \begin{cfuncdesc}{TYPE}{_PyObject_NEW}{TYPE, PyTypeObject *}
5588
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2811 \end{cfuncdesc}
53cdf94b652b Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents: 5536
diff changeset
2812
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2813 \begin{cfuncdesc}{TYPE}{_PyObject_NEW_VAR}{TYPE, PyTypeObject *, int size}
5588
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
7269
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2816
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2817 \chapter{Debugging}
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2818
682d3e5b267f Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents: 7268
diff changeset
2819 XXX Explain Py_DEBUG, Py_TRACE_REFS, Py_REF_DEBUG.
6991
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
2820
f349bf0e9322 A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents: 6653
diff changeset
2821
5536
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2822 \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
2823
c6f04e965508 Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff changeset
2824 \end{document}