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