Mercurial > cpython-lru_cache-weakref
annotate Doc/api/api.tex @ 20354:fdc1914406e2 legacy-trunk
Updated, and added a very terse description of PyMac_SetConsoleHandler().
| author | Jack Jansen <jack.jansen@cwi.nl> |
|---|---|
| date | Tue, 09 Oct 2001 23:14:06 +0000 |
| parents | c853d246f3c8 |
| children | 946bebd00132 |
| rev | line source |
|---|---|
|
7527
26a8771a4cfd
Convert LaTeX support to create a new class of documents. HTML generation
Fred Drake <fdrake@acm.org>
parents:
7493
diff
changeset
|
1 \documentclass{manual} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2 |
|
6417
4491f84ac223
Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents:
6390
diff
changeset
|
3 \title{Python/C API Reference Manual} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
4 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
5 \input{boilerplate} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
6 |
|
15953
8349b4dfc51a
Undoing the whitespace patches which sneaked into the earlier patch.
Marc-André Lemburg <mal@egenix.com>
parents:
15952
diff
changeset
|
7 \makeindex % tell \index to actually write the .idx file |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
8 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
9 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
10 \begin{document} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
11 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
12 \maketitle |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
13 |
|
8782
ae3e2eaef9b9
Update to use a separate page for front matter.
Fred Drake <fdrake@acm.org>
parents:
8138
diff
changeset
|
14 \ifhtml |
|
ae3e2eaef9b9
Update to use a separate page for front matter.
Fred Drake <fdrake@acm.org>
parents:
8138
diff
changeset
|
15 \chapter*{Front Matter\label{front}} |
|
ae3e2eaef9b9
Update to use a separate page for front matter.
Fred Drake <fdrake@acm.org>
parents:
8138
diff
changeset
|
16 \fi |
|
ae3e2eaef9b9
Update to use a separate page for front matter.
Fred Drake <fdrake@acm.org>
parents:
8138
diff
changeset
|
17 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
18 \input{copyright} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
19 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
20 \begin{abstract} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
21 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
22 \noindent |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
23 This manual documents the API used by C and \Cpp{} programmers who |
| 7308 | 24 want to write extension modules or embed Python. It is a companion to |
|
11451
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
25 \citetitle[../ext/ext.html]{Extending and Embedding the Python |
|
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
26 Interpreter}, which describes the general principles of extension |
|
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
27 writing but does not document the API functions in detail. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
28 |
|
6991
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
29 \strong{Warning:} The current version of this document is incomplete. |
|
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
30 I hope that it is nevertheless useful. I will continue to work on it, |
|
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
31 and release new versions from time to time, independent from Python |
|
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
32 source code releases. |
|
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
33 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
34 \end{abstract} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
35 |
|
7092
8a55643e667f
Removed \mytableofcontents; just use \tableofcontents.
Fred Drake <fdrake@acm.org>
parents:
7081
diff
changeset
|
36 \tableofcontents |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
37 |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
38 % XXX Consider moving all this back to ext.tex and giving api.tex |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
39 % XXX a *really* short intro only. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
40 |
| 10163 | 41 \chapter{Introduction \label{intro}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
42 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
43 The Application Programmer's Interface to Python gives C and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
44 \Cpp{} programmers access to the Python interpreter at a variety of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
45 levels. The API is equally usable from \Cpp{}, but for brevity it is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
46 generally referred to as the Python/C API. There are two |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
47 fundamentally different reasons for using the Python/C API. The first |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
48 reason is to write \emph{extension modules} for specific purposes; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
49 these are C modules that extend the Python interpreter. This is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
50 probably the most common use. The second reason is to use Python as a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
51 component in a larger application; this technique is generally |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
52 referred to as \dfn{embedding} Python in an application. |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
53 |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
54 Writing an extension module is a relatively well-understood process, |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
55 where a ``cookbook'' approach works well. There are several tools |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
56 that automate the process to some extent. While people have embedded |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
57 Python in other applications since its early existence, the process of |
| 17875 | 58 embedding Python is less straightforward than writing an extension. |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
59 |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
60 Many API functions are useful independent of whether you're embedding |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
61 or extending Python; moreover, most applications that embed Python |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
62 will need to provide a custom extension as well, so it's probably a |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
63 good idea to become familiar with writing an extension before |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
64 attempting to embed Python in a real application. |
|
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
65 |
| 10163 | 66 |
| 67 \section{Include Files \label{includes}} | |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
68 |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
69 All function, type and macro definitions needed to use the Python/C |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
70 API are included in your code by the following line: |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
71 |
| 7308 | 72 \begin{verbatim} |
| 73 #include "Python.h" | |
| 74 \end{verbatim} | |
| 75 | |
| 76 This implies inclusion of the following standard headers: | |
|
14870
e35a3a772dca
Note that including Python.h includes limits.h when available.
Fred Drake <fdrake@acm.org>
parents:
14782
diff
changeset
|
77 \code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, |
|
e35a3a772dca
Note that including Python.h includes limits.h when available.
Fred Drake <fdrake@acm.org>
parents:
14782
diff
changeset
|
78 \code{<limits.h>}, and \code{<stdlib.h>} (if available). |
|
19771
432591328410
Document the rule that Python.h must be included before any standard
Fred Drake <fdrake@acm.org>
parents:
19735
diff
changeset
|
79 Since Python may define some pre-processor definitions which affect |
|
432591328410
Document the rule that Python.h must be included before any standard
Fred Drake <fdrake@acm.org>
parents:
19735
diff
changeset
|
80 the standard headers on some systems, you must include \file{Python.h} |
|
432591328410
Document the rule that Python.h must be included before any standard
Fred Drake <fdrake@acm.org>
parents:
19735
diff
changeset
|
81 before any standard headers are included. |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
82 |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
83 All user visible names defined by Python.h (except those defined by |
| 7308 | 84 the included standard headers) have one of the prefixes \samp{Py} or |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
85 \samp{_Py}. Names beginning with \samp{_Py} are for internal use by |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
86 the Python implementation and should not be used by extension writers. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
87 Structure member names do not have a reserved prefix. |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
88 |
| 7308 | 89 \strong{Important:} user code should never define names that begin |
| 90 with \samp{Py} or \samp{_Py}. This confuses the reader, and | |
| 91 jeopardizes the portability of the user code to future Python | |
| 92 versions, which may define additional names beginning with one of | |
| 93 these prefixes. | |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
94 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
95 The header files are typically installed with Python. On \UNIX, these |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
96 are located in the directories |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
97 \file{\envvar{prefix}/include/python\var{version}/} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
98 \file{\envvar{exec_prefix}/include/python\var{version}/}, where |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
99 \envvar{prefix} and \envvar{exec_prefix} are defined by the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
100 corresponding parameters to Python's \program{configure} script and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
101 \var{version} is \code{sys.version[:3]}. On Windows, the headers are |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
102 installed in \file{\envvar{prefix}/include}, where \envvar{prefix} is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
103 the installation directory specified to the installer. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
104 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
105 To include the headers, place both directories (if different) on your |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
106 compiler's search path for includes. Do \emph{not} place the parent |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
107 directories on the search path and then use |
|
14557
a71385f8b4da
Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents:
14553
diff
changeset
|
108 \samp{\#include <python\shortversion/Python.h>}; this will break on |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
109 multi-platform builds since the platform independent headers under |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
110 \envvar{prefix} include the platform specific headers from |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
111 \envvar{exec_prefix}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
112 |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
113 \Cpp{} users should note that though the API is defined entirely using |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
114 C, the header files do properly declare the entry points to be |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
115 \code{extern "C"}, so there is no need to do anything special to use |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
116 the API from \Cpp. |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
117 |
| 10163 | 118 |
| 119 \section{Objects, Types and Reference Counts \label{objects}} | |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
120 |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
121 Most Python/C API functions have one or more arguments as well as a |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
122 return value of type \ctype{PyObject*}. This type is a pointer |
| 7308 | 123 to an opaque data type representing an arbitrary Python |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
124 object. Since all Python object types are treated the same way by the |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
125 Python language in most situations (e.g., assignments, scope rules, |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
126 and argument passing), it is only fitting that they should be |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
127 represented by a single C type. Almost all Python objects live on the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
128 heap: you never declare an automatic or static variable of type |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
129 \ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
130 be declared. The sole exception are the type objects\obindex{type}; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
131 since these must never be deallocated, they are typically static |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
132 \ctype{PyTypeObject} objects. |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
133 |
| 7308 | 134 All Python objects (even Python integers) have a \dfn{type} and a |
| 135 \dfn{reference count}. An object's type determines what kind of object | |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
136 it is (e.g., an integer, a list, or a user-defined function; there are |
|
11451
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
137 many more as explained in the \citetitle[../ref/ref.html]{Python |
|
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
138 Reference Manual}). For each of the well-known types there is a macro |
|
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
139 to check whether an object is of that type; for instance, |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
140 \samp{PyList_Check(\var{a})} is true if (and only if) the object |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
141 pointed to by \var{a} is a Python list. |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
142 |
| 10163 | 143 |
| 144 \subsection{Reference Counts \label{refcounts}} | |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
145 |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
146 The reference count is important because today's computers have a |
|
8029
95142c8a09c8
Typo: (and often severly limited) -- severely
Fred Drake <fdrake@acm.org>
parents:
8021
diff
changeset
|
147 finite (and often severely limited) memory size; it counts how many |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
148 different places there are that have a reference to an object. Such a |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
149 place could be another object, or a global (or static) C variable, or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
150 a local variable in some C function. When an object's reference count |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
151 becomes zero, the object is deallocated. If it contains references to |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
152 other objects, their reference count is decremented. Those other |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
153 objects may be deallocated in turn, if this decrement makes their |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
154 reference count become zero, and so on. (There's an obvious problem |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
155 with objects that reference each other here; for now, the solution is |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
156 ``don't do that.'') |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
157 |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
158 Reference counts are always manipulated explicitly. The normal way is |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
159 to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
160 increment an object's reference count by one, and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
161 \cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
162 one. The \cfunction{Py_DECREF()} macro is considerably more complex |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
163 than the incref one, since it must check whether the reference count |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
164 becomes zero and then cause the object's deallocator to be called. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
165 The deallocator is a function pointer contained in the object's type |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
166 structure. The type-specific deallocator takes care of decrementing |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
167 the reference counts for other objects contained in the object if this |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
168 is a compound object type, such as a list, as well as performing any |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
169 additional finalization that's needed. There's no chance that the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
170 reference count can overflow; at least as many bits are used to hold |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
171 the reference count as there are distinct memory locations in virtual |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
172 memory (assuming \code{sizeof(long) >= sizeof(char*)}). Thus, the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
173 reference count increment is a simple operation. |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
174 |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
175 It is not necessary to increment an object's reference count for every |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
176 local variable that contains a pointer to an object. In theory, the |
| 7308 | 177 object's reference count goes up by one when the variable is made to |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
178 point to it and it goes down by one when the variable goes out of |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
179 scope. However, these two cancel each other out, so at the end the |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
180 reference count hasn't changed. The only real reason to use the |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
181 reference count is to prevent the object from being deallocated as |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
182 long as our variable is pointing to it. If we know that there is at |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
183 least one other reference to the object that lives at least as long as |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
184 our variable, there is no need to increment the reference count |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
185 temporarily. An important situation where this arises is in objects |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
186 that are passed as arguments to C functions in an extension module |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
187 that are called from Python; the call mechanism guarantees to hold a |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
188 reference to every argument for the duration of the call. |
|
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
189 |
| 7308 | 190 However, a common pitfall is to extract an object from a list and |
| 191 hold on to it for a while without incrementing its reference count. | |
| 192 Some other operation might conceivably remove the object from the | |
| 193 list, decrementing its reference count and possible deallocating it. | |
| 194 The real danger is that innocent-looking operations may invoke | |
| 195 arbitrary Python code which could do this; there is a code path which | |
| 196 allows control to flow back to the user from a \cfunction{Py_DECREF()}, | |
| 197 so almost any operation is potentially dangerous. | |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
198 |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
199 A safe approach is to always use the generic operations (functions |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
200 whose name begins with \samp{PyObject_}, \samp{PyNumber_}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
201 \samp{PySequence_} or \samp{PyMapping_}). These operations always |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
202 increment the reference count of the object they return. This leaves |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
203 the caller with the responsibility to call |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
204 \cfunction{Py_DECREF()} when they are done with the result; this soon |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
205 becomes second nature. |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
206 |
| 10163 | 207 |
| 208 \subsubsection{Reference Count Details \label{refcountDetails}} | |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
209 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
210 The reference count behavior of functions in the Python/C API is best |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
211 explained in terms of \emph{ownership of references}. Note that we |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
212 talk of owning references, never of owning objects; objects are always |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
213 shared! When a function owns a reference, it has to dispose of it |
| 7308 | 214 properly --- either by passing ownership on (usually to its caller) or |
| 215 by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When | |
| 216 a function passes ownership of a reference on to its caller, the | |
| 217 caller is said to receive a \emph{new} reference. When no ownership | |
| 218 is transferred, the caller is said to \emph{borrow} the reference. | |
| 219 Nothing needs to be done for a borrowed reference. | |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
220 |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
221 Conversely, when a calling function passes it a reference to an |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
222 object, there are two possibilities: the function \emph{steals} a |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
223 reference to the object, or it does not. Few functions steal |
| 7308 | 224 references; the two notable exceptions are |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
225 \cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
226 \cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which |
| 7308 | 227 steal a reference to the item (but not to the tuple or list into which |
|
8029
95142c8a09c8
Typo: (and often severly limited) -- severely
Fred Drake <fdrake@acm.org>
parents:
8021
diff
changeset
|
228 the item is put!). These functions were designed to steal a reference |
| 7308 | 229 because of a common idiom for populating a tuple or list with newly |
| 230 created objects; for example, the code to create the tuple \code{(1, | |
| 231 2, "three")} could look like this (forgetting about error handling for | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
232 the moment; a better way to code this is shown below): |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
233 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
234 \begin{verbatim} |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
235 PyObject *t; |
| 7782 | 236 |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
237 t = PyTuple_New(3); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
238 PyTuple_SetItem(t, 0, PyInt_FromLong(1L)); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
239 PyTuple_SetItem(t, 1, PyInt_FromLong(2L)); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
240 PyTuple_SetItem(t, 2, PyString_FromString("three")); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
241 \end{verbatim} |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
242 |
| 7308 | 243 Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to |
| 244 set tuple items; \cfunction{PySequence_SetItem()} and | |
| 245 \cfunction{PyObject_SetItem()} refuse to do this since tuples are an | |
| 246 immutable data type. You should only use | |
| 247 \cfunction{PyTuple_SetItem()} for tuples that you are creating | |
|
6991
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
248 yourself. |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
249 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
250 Equivalent code for populating a list can be written using |
| 7308 | 251 \cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code |
| 252 can also use \cfunction{PySequence_SetItem()}; this illustrates the | |
| 253 difference between the two (the extra \cfunction{Py_DECREF()} calls): | |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
254 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
255 \begin{verbatim} |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
256 PyObject *l, *x; |
| 7782 | 257 |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
258 l = PyList_New(3); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
259 x = PyInt_FromLong(1L); |
|
6991
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
260 PySequence_SetItem(l, 0, x); Py_DECREF(x); |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
261 x = PyInt_FromLong(2L); |
|
6991
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
262 PySequence_SetItem(l, 1, x); Py_DECREF(x); |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
263 x = PyString_FromString("three"); |
|
6991
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
264 PySequence_SetItem(l, 2, x); Py_DECREF(x); |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
265 \end{verbatim} |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
266 |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
267 You might find it strange that the ``recommended'' approach takes more |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
268 code. However, in practice, you will rarely use these ways of |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
269 creating and populating a tuple or list. There's a generic function, |
| 7308 | 270 \cfunction{Py_BuildValue()}, that can create most common objects from |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
271 C values, directed by a \dfn{format string}. For example, the |
| 7308 | 272 above two blocks of code could be replaced by the following (which |
| 273 also takes care of the error checking): | |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
274 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
275 \begin{verbatim} |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
276 PyObject *t, *l; |
| 7782 | 277 |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
278 t = Py_BuildValue("(iis)", 1, 2, "three"); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
279 l = Py_BuildValue("[iis]", 1, 2, "three"); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
280 \end{verbatim} |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
281 |
| 7308 | 282 It is much more common to use \cfunction{PyObject_SetItem()} and |
| 283 friends with items whose references you are only borrowing, like | |
| 284 arguments that were passed in to the function you are writing. In | |
| 285 that case, their behaviour regarding reference counts is much saner, | |
| 286 since you don't have to increment a reference count so you can give a | |
| 287 reference away (``have it be stolen''). For example, this function | |
| 288 sets all items of a list (actually, any mutable sequence) to a given | |
| 289 item: | |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
290 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
291 \begin{verbatim} |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
292 int set_all(PyObject *target, PyObject *item) |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
293 { |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
294 int i, n; |
| 7782 | 295 |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
296 n = PyObject_Length(target); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
297 if (n < 0) |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
298 return -1; |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
299 for (i = 0; i < n; i++) { |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
300 if (PyObject_SetItem(target, i, item) < 0) |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
301 return -1; |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
302 } |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
303 return 0; |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
304 } |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
305 \end{verbatim} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
306 \ttindex{set_all()} |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
307 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
308 The situation is slightly different for function return values. |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
309 While passing a reference to most functions does not change your |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
310 ownership responsibilities for that reference, many functions that |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
311 return a referece to an object give you ownership of the reference. |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
312 The reason is simple: in many cases, the returned object is created |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
313 on the fly, and the reference you get is the only reference to the |
| 7308 | 314 object. Therefore, the generic functions that return object |
| 315 references, like \cfunction{PyObject_GetItem()} and | |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
316 \cfunction{PySequence_GetItem()}, always return a new reference (the |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
317 caller becomes the owner of the reference). |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
318 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
319 It is important to realize that whether you own a reference returned |
| 7308 | 320 by a function depends on which function you call only --- \emph{the |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
321 plumage} (the type of the type of the object passed as an |
| 7308 | 322 argument to the function) \emph{doesn't enter into it!} Thus, if you |
| 323 extract an item from a list using \cfunction{PyList_GetItem()}, you | |
| 324 don't own the reference --- but if you obtain the same item from the | |
| 325 same list using \cfunction{PySequence_GetItem()} (which happens to | |
| 326 take exactly the same arguments), you do own a reference to the | |
| 327 returned object. | |
| 328 | |
| 329 Here is an example of how you could write a function that computes the | |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
330 sum of the items in a list of integers; once using |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
331 \cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
332 \cfunction{PySequence_GetItem()}\ttindex{PySequence_GetItem()}. |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
333 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
334 \begin{verbatim} |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
335 long sum_list(PyObject *list) |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
336 { |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
337 int i, n; |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
338 long total = 0; |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
339 PyObject *item; |
| 7782 | 340 |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
341 n = PyList_Size(list); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
342 if (n < 0) |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
343 return -1; /* Not a list */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
344 for (i = 0; i < n; i++) { |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
345 item = PyList_GetItem(list, i); /* Can't fail */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
346 if (!PyInt_Check(item)) continue; /* Skip non-integers */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
347 total += PyInt_AsLong(item); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
348 } |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
349 return total; |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
350 } |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
351 \end{verbatim} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
352 \ttindex{sum_list()} |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
353 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
354 \begin{verbatim} |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
355 long sum_sequence(PyObject *sequence) |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
356 { |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
357 int i, n; |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
358 long total = 0; |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
359 PyObject *item; |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
360 n = PySequence_Length(sequence); |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
361 if (n < 0) |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
362 return -1; /* Has no length */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
363 for (i = 0; i < n; i++) { |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
364 item = PySequence_GetItem(sequence, i); |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
365 if (item == NULL) |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
366 return -1; /* Not a sequence, or other failure */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
367 if (PyInt_Check(item)) |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
368 total += PyInt_AsLong(item); |
|
6991
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
369 Py_DECREF(item); /* Discard reference ownership */ |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
370 } |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
371 return total; |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
372 } |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
373 \end{verbatim} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
374 \ttindex{sum_sequence()} |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
375 |
| 10163 | 376 |
| 377 \subsection{Types \label{types}} | |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
378 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
379 There are few other data types that play a significant role in |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
380 the Python/C API; most are simple C types such as \ctype{int}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
381 \ctype{long}, \ctype{double} and \ctype{char*}. A few structure types |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
382 are used to describe static tables used to list the functions exported |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
383 by a module or the data attributes of a new object type, and another |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
384 is used to describe the value of a complex number. These will |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
385 be discussed together with the functions that use them. |
|
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
386 |
| 10163 | 387 |
| 388 \section{Exceptions \label{exceptions}} | |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
389 |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
390 The Python programmer only needs to deal with exceptions if specific |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
391 error handling is required; unhandled exceptions are automatically |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
392 propagated to the caller, then to the caller's caller, and so on, until |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
393 they reach the top-level interpreter, where they are reported to the |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
394 user accompanied by a stack traceback. |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
395 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
396 For C programmers, however, error checking always has to be explicit. |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
397 All functions in the Python/C API can raise exceptions, unless an |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
398 explicit claim is made otherwise in a function's documentation. In |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
399 general, when a function encounters an error, it sets an exception, |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
400 discards any object references that it owns, and returns an |
| 7308 | 401 error indicator --- usually \NULL{} or \code{-1}. A few functions |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
402 return a Boolean true/false result, with false indicating an error. |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
403 Very few functions return no explicit error indicator or have an |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
404 ambiguous return value, and require explicit testing for errors with |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
405 \cfunction{PyErr_Occurred()}\ttindex{PyErr_Occurred()}. |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
406 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
407 Exception state is maintained in per-thread storage (this is |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
408 equivalent to using global storage in an unthreaded application). A |
| 7782 | 409 thread can be in one of two states: an exception has occurred, or not. |
| 7308 | 410 The function \cfunction{PyErr_Occurred()} can be used to check for |
| 411 this: it returns a borrowed reference to the exception type object | |
| 412 when an exception has occurred, and \NULL{} otherwise. There are a | |
| 413 number of functions to set the exception state: | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
414 \cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
415 common (though not the most general) function to set the exception |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
416 state, and \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} clears the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
417 exception state. |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
418 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
419 The full exception state consists of three objects (all of which can |
| 7308 | 420 be \NULL{}): the exception type, the corresponding exception |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
421 value, and the traceback. These have the same meanings as the Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
422 \withsubitem{(in module sys)}{ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
423 \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
424 objects \code{sys.exc_type}, \code{sys.exc_value}, and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
425 \code{sys.exc_traceback}; however, they are not the same: the Python |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
426 objects represent the last exception being handled by a Python |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
427 \keyword{try} \ldots\ \keyword{except} statement, while the C level |
| 7308 | 428 exception state only exists while an exception is being passed on |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
429 between C functions until it reaches the Python bytecode interpreter's |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
430 main loop, which takes care of transferring it to \code{sys.exc_type} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
431 and friends. |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
432 |
| 7782 | 433 Note that starting with Python 1.5, the preferred, thread-safe way to |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
434 access the exception state from Python code is to call the function |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
435 \withsubitem{(in module sys)}{\ttindex{exc_info()}} |
| 7308 | 436 \function{sys.exc_info()}, which returns the per-thread exception state |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
437 for Python code. Also, the semantics of both ways to access the |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
438 exception state have changed so that a function which catches an |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
439 exception will save and restore its thread's exception state so as to |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
440 preserve the exception state of its caller. This prevents common bugs |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
441 in exception handling code caused by an innocent-looking function |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
442 overwriting the exception being handled; it also reduces the often |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
443 unwanted lifetime extension for objects that are referenced by the |
| 7782 | 444 stack frames in the traceback. |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
445 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
446 As a general principle, a function that calls another function to |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
447 perform some task should check whether the called function raised an |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
448 exception, and if so, pass the exception state on to its caller. It |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
449 should discard any object references that it owns, and return an |
| 7308 | 450 error indicator, but it should \emph{not} set another exception --- |
| 451 that would overwrite the exception that was just raised, and lose | |
| 452 important information about the exact cause of the error. | |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
453 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
454 A simple example of detecting exceptions and passing them on is shown |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
455 in the \cfunction{sum_sequence()}\ttindex{sum_sequence()} example |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
456 above. It so happens that that example doesn't need to clean up any |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
457 owned references when it detects an error. The following example |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
458 function shows some error cleanup. First, to remind you why you like |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
459 Python, we show the equivalent Python code: |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
460 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
461 \begin{verbatim} |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
462 def incr_item(dict, key): |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
463 try: |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
464 item = dict[key] |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
465 except KeyError: |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
466 item = 0 |
|
15453
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
467 dict[key] = item + 1 |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
468 \end{verbatim} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
469 \ttindex{incr_item()} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
470 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
471 Here is the corresponding C code, in all its glory: |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
472 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
473 \begin{verbatim} |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
474 int incr_item(PyObject *dict, PyObject *key) |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
475 { |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
476 /* Objects all initialized to NULL for Py_XDECREF */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
477 PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL; |
|
6991
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
478 int rv = -1; /* Return value initialized to -1 (failure) */ |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
479 |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
480 item = PyObject_GetItem(dict, key); |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
481 if (item == NULL) { |
| 7782 | 482 /* Handle KeyError only: */ |
|
15453
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
483 if (!PyErr_ExceptionMatches(PyExc_KeyError)) |
|
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
484 goto error; |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
485 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
486 /* Clear the error and use zero: */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
487 PyErr_Clear(); |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
488 item = PyInt_FromLong(0L); |
|
15453
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
489 if (item == NULL) |
|
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
490 goto error; |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
491 } |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
492 const_one = PyInt_FromLong(1L); |
|
15453
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
493 if (const_one == NULL) |
|
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
494 goto error; |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
495 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
496 incremented_item = PyNumber_Add(item, const_one); |
|
15453
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
497 if (incremented_item == NULL) |
|
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
498 goto error; |
|
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
499 |
|
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
500 if (PyObject_SetItem(dict, key, incremented_item) < 0) |
|
7721fb509462
In the first discussion showing how to handle exceptions from C, make the
Fred Drake <fdrake@acm.org>
parents:
15444
diff
changeset
|
501 goto error; |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
502 rv = 0; /* Success */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
503 /* Continue with cleanup code */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
504 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
505 error: |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
506 /* Cleanup code, shared by success and failure path */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
507 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
508 /* Use Py_XDECREF() to ignore NULL references */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
509 Py_XDECREF(item); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
510 Py_XDECREF(const_one); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
511 Py_XDECREF(incremented_item); |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
512 |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
513 return rv; /* -1 for error, 0 for success */ |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
514 } |
|
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
515 \end{verbatim} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
516 \ttindex{incr_item()} |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
517 |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
518 This example represents an endorsed use of the \keyword{goto} statement |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
519 in C! It illustrates the use of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
520 \cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
521 \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
522 handle specific exceptions, and the use of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
523 \cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
524 dispose of owned references that may be \NULL{} (note the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
525 \character{X} in the name; \cfunction{Py_DECREF()} would crash when |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
526 confronted with a \NULL{} reference). It is important that the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
527 variables used to hold owned references are initialized to \NULL{} for |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
528 this to work; likewise, the proposed return value is initialized to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
529 \code{-1} (failure) and only set to success after the final call made |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
530 is successful. |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
531 |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
532 |
| 10163 | 533 \section{Embedding Python \label{embedding}} |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
534 |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
535 The one important task that only embedders (as opposed to extension |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
536 writers) of the Python interpreter have to worry about is the |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
537 initialization, and possibly the finalization, of the Python |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
538 interpreter. Most functionality of the interpreter can only be used |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
539 after the interpreter has been initialized. |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
540 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
541 The basic initialization function is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
542 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. |
| 7308 | 543 This initializes the table of loaded modules, and creates the |
|
7310
6095a472f574
Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents:
7309
diff
changeset
|
544 fundamental modules \module{__builtin__}\refbimodindex{__builtin__}, |
|
19242
d99c1240d0ac
Add "exceptions" to the list of fundamental modules
Fred Drake <fdrake@acm.org>
parents:
19156
diff
changeset
|
545 \module{__main__}\refbimodindex{__main__}, \module{sys}\refbimodindex{sys}, |
|
d99c1240d0ac
Add "exceptions" to the list of fundamental modules
Fred Drake <fdrake@acm.org>
parents:
19156
diff
changeset
|
546 and \module{exceptions}.\refbimodindex{exceptions} It also initializes |
|
d99c1240d0ac
Add "exceptions" to the list of fundamental modules
Fred Drake <fdrake@acm.org>
parents:
19156
diff
changeset
|
547 the module search path (\code{sys.path}).% |
| 7782 | 548 \indexiii{module}{search}{path} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
549 \withsubitem{(in module sys)}{\ttindex{path}} |
| 7308 | 550 |
| 551 \cfunction{Py_Initialize()} does not set the ``script argument list'' | |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
552 (\code{sys.argv}). If this variable is needed by Python code that |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
553 will be executed later, it must be set explicitly with a call to |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
554 \code{PySys_SetArgv(\var{argc}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
555 \var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
556 \cfunction{Py_Initialize()}. |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
557 |
| 7081 | 558 On most systems (in particular, on \UNIX{} and Windows, although the |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
559 details are slightly different), |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
560 \cfunction{Py_Initialize()} calculates the module search path based |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
561 upon its best guess for the location of the standard Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
562 interpreter executable, assuming that the Python library is found in a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
563 fixed location relative to the Python interpreter executable. In |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
564 particular, it looks for a directory named |
|
14557
a71385f8b4da
Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents:
14553
diff
changeset
|
565 \file{lib/python\shortversion} relative to the parent directory where |
|
a71385f8b4da
Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents:
14553
diff
changeset
|
566 the executable named \file{python} is found on the shell command |
|
a71385f8b4da
Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents:
14553
diff
changeset
|
567 search path (the environment variable \envvar{PATH}). |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
568 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
569 For instance, if the Python executable is found in |
| 7308 | 570 \file{/usr/local/bin/python}, it will assume that the libraries are in |
|
14557
a71385f8b4da
Use \shortversion in a number of places.
Fred Drake <fdrake@acm.org>
parents:
14553
diff
changeset
|
571 \file{/usr/local/lib/python\shortversion}. (In fact, this particular path |
| 7308 | 572 is also the ``fallback'' location, used when no executable file named |
| 7782 | 573 \file{python} is found along \envvar{PATH}.) The user can override |
| 574 this behavior by setting the environment variable \envvar{PYTHONHOME}, | |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
575 or insert additional directories in front of the standard path by |
| 7782 | 576 setting \envvar{PYTHONPATH}. |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
577 |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
578 The embedding application can steer the search by calling |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
579 \code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling |
| 7782 | 580 \cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still |
| 581 overrides this and \envvar{PYTHONPATH} is still inserted in front of | |
| 7308 | 582 the standard path. An application that requires total control has to |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
583 provide its own implementation of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
584 \cfunction{Py_GetPath()}\ttindex{Py_GetPath()}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
585 \cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
586 \cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
587 \cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
588 defined in \file{Modules/getpath.c}). |
|
6040
1a43699108a6
Added new intro sections (incomplete); fixed various typos
Guido van Rossum <guido@python.org>
parents:
5588
diff
changeset
|
589 |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
590 Sometimes, it is desirable to ``uninitialize'' Python. For instance, |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
591 the application may want to start over (make another call to |
| 7308 | 592 \cfunction{Py_Initialize()}) or the application is simply done with its |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
593 use of Python and wants to free all memory allocated by Python. This |
| 7308 | 594 can be accomplished by calling \cfunction{Py_Finalize()}. The function |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
595 \cfunction{Py_IsInitialized()}\ttindex{Py_IsInitialized()} returns |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
596 true if Python is currently in the initialized state. More |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
597 information about these functions is given in a later chapter. |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
598 |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
599 |
| 10163 | 600 \chapter{The Very High Level Layer \label{veryhigh}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
601 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
602 The functions in this chapter will let you execute Python source code |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
603 given in a file or a buffer, but they will not let you interact in a |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
604 more detailed way with the interpreter. |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
605 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
606 Several of these functions accept a start symbol from the grammar as a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
607 parameter. The available start symbols are \constant{Py_eval_input}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
608 \constant{Py_file_input}, and \constant{Py_single_input}. These are |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
609 described following the functions which accept them as parameters. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
610 |
|
13959
8be7524085d6
In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents:
13929
diff
changeset
|
611 Note also that several of these functions take \ctype{FILE*} |
|
8be7524085d6
In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents:
13929
diff
changeset
|
612 parameters. On particular issue which needs to be handled carefully |
|
8be7524085d6
In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents:
13929
diff
changeset
|
613 is that the \ctype{FILE} structure for different C libraries can be |
|
8be7524085d6
In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents:
13929
diff
changeset
|
614 different and incompatible. Under Windows (at least), it is possible |
|
8be7524085d6
In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents:
13929
diff
changeset
|
615 for dynamically linked extensions to actually use different libraries, |
|
8be7524085d6
In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents:
13929
diff
changeset
|
616 so care should be taken that \ctype{FILE*} parameters are only passed |
|
8be7524085d6
In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents:
13929
diff
changeset
|
617 to these functions if it is certain that they were created by the same |
|
8be7524085d6
In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents:
13929
diff
changeset
|
618 library that the Python runtime is using. |
|
8be7524085d6
In the section on the "Very High Level Layer", address concerns brought up
Fred Drake <fdrake@acm.org>
parents:
13929
diff
changeset
|
619 |
|
17877
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
620 \begin{cfuncdesc}{int}{Py_Main}{int argc, char **argv} |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
621 The main program for the standard interpreter. This is made |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
622 available for programs which embed Python. The \var{argc} and |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
623 \var{argv} parameters should be prepared exactly as those which are |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
624 passed to a C program's \cfunction{main()} function. It is |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
625 important to note that the argument list may be modified (but the |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
626 contents of the strings pointed to by the argument list are not). |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
627 The return value will be the integer passed to the |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
628 \function{sys.exit()} function, \code{1} if the interpreter exits |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
629 due to an exception, or \code{2} if the parameter list does not |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
630 represent a valid Python command line. |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
631 \end{cfuncdesc} |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
632 |
| 7782 | 633 \begin{cfuncdesc}{int}{PyRun_AnyFile}{FILE *fp, char *filename} |
|
10786
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
634 If \var{fp} refers to a file associated with an interactive device |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
635 (console or terminal input or \UNIX{} pseudo-terminal), return the |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
636 value of \cfunction{PyRun_InteractiveLoop()}, otherwise return the |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
637 result of \cfunction{PyRun_SimpleFile()}. If \var{filename} is |
| 13929 | 638 \NULL{}, this function uses \code{"???"} as the filename. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
639 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
640 |
| 7782 | 641 \begin{cfuncdesc}{int}{PyRun_SimpleString}{char *command} |
|
10786
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
642 Executes the Python source code from \var{command} in the |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
643 \module{__main__} module. If \module{__main__} does not already |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
644 exist, it is created. Returns \code{0} on success or \code{-1} if |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
645 an exception was raised. If there was an error, there is no way to |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
646 get the exception information. |
| 7782 | 647 \end{cfuncdesc} |
| 648 | |
| 649 \begin{cfuncdesc}{int}{PyRun_SimpleFile}{FILE *fp, char *filename} | |
|
10786
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
650 Similar to \cfunction{PyRun_SimpleString()}, but the Python source |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
651 code is read from \var{fp} instead of an in-memory string. |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
652 \var{filename} should be the name of the file. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
653 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
654 |
| 7782 | 655 \begin{cfuncdesc}{int}{PyRun_InteractiveOne}{FILE *fp, char *filename} |
| 13929 | 656 Read and execute a single statement from a file associated with an |
| 657 interactive device. If \var{filename} is \NULL, \code{"???"} is | |
| 658 used instead. The user will be prompted using \code{sys.ps1} and | |
| 659 \code{sys.ps2}. Returns \code{0} when the input was executed | |
| 660 successfully, \code{-1} if there was an exception, or an error code | |
| 661 from the \file{errcode.h} include file distributed as part of Python | |
| 662 in case of a parse error. (Note that \file{errcode.h} is not | |
| 663 included by \file{Python.h}, so must be included specifically if | |
| 664 needed.) | |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
665 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
666 |
| 7782 | 667 \begin{cfuncdesc}{int}{PyRun_InteractiveLoop}{FILE *fp, char *filename} |
| 13929 | 668 Read and execute statements from a file associated with an |
| 669 interactive device until \EOF{} is reached. If \var{filename} is | |
| 670 \NULL, \code{"???"} is used instead. The user will be prompted | |
| 671 using \code{sys.ps1} and \code{sys.ps2}. Returns \code{0} at \EOF. | |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
672 \end{cfuncdesc} |
|
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
673 |
| 7782 | 674 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseString}{char *str, |
| 675 int start} | |
|
10786
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
676 Parse Python source code from \var{str} using the start token |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
677 \var{start}. The result can be used to create a code object which |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
678 can be evaluated efficiently. This is useful if a code fragment |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
679 must be evaluated many times. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
680 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
681 |
| 7782 | 682 \begin{cfuncdesc}{struct _node*}{PyParser_SimpleParseFile}{FILE *fp, |
| 683 char *filename, int start} | |
|
10786
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
684 Similar to \cfunction{PyParser_SimpleParseString()}, but the Python |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
685 source code is read from \var{fp} instead of an in-memory string. |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
686 \var{filename} should be the name of the file. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
687 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
688 |
| 7782 | 689 \begin{cfuncdesc}{PyObject*}{PyRun_String}{char *str, int start, |
| 690 PyObject *globals, | |
| 691 PyObject *locals} | |
|
10786
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
692 Execute Python source code from \var{str} in the context specified |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
693 by the dictionaries \var{globals} and \var{locals}. The parameter |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
694 \var{start} specifies the start token that should be used to parse |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
695 the source code. |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
696 |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
697 Returns the result of executing the code as a Python object, or |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
698 \NULL{} if an exception was raised. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
699 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
700 |
| 7782 | 701 \begin{cfuncdesc}{PyObject*}{PyRun_File}{FILE *fp, char *filename, |
| 702 int start, PyObject *globals, | |
| 703 PyObject *locals} | |
|
10786
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
704 Similar to \cfunction{PyRun_String()}, but the Python source code is |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
705 read from \var{fp} instead of an in-memory string. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
706 \var{filename} should be the name of the file. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
707 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
708 |
| 7782 | 709 \begin{cfuncdesc}{PyObject*}{Py_CompileString}{char *str, char *filename, |
| 710 int start} | |
|
10786
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
711 Parse and compile the Python source code in \var{str}, returning the |
|
a34d6656f8e2
Fill in a few holes in the "Very High Level" chapter.
Fred Drake <fdrake@acm.org>
parents:
10219
diff
changeset
|
712 resulting code object. The start token is given by \var{start}; |
|
11222
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
713 this can be used to constrain the code which can be compiled and should |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
714 be \constant{Py_eval_input}, \constant{Py_file_input}, or |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
715 \constant{Py_single_input}. The filename specified by |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
716 \var{filename} is used to construct the code object and may appear |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
717 in tracebacks or \exception{SyntaxError} exception messages. This |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
718 returns \NULL{} if the code cannot be parsed or compiled. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
719 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
720 |
|
11222
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
721 \begin{cvardesc}{int}{Py_eval_input} |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
722 The start symbol from the Python grammar for isolated expressions; |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
723 for use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. |
|
11222
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
724 \end{cvardesc} |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
725 |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
726 \begin{cvardesc}{int}{Py_file_input} |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
727 The start symbol from the Python grammar for sequences of statements |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
728 as read from a file or other source; for use with |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
729 \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. This is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
730 the symbol to use when compiling arbitrarily long Python source code. |
|
11222
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
731 \end{cvardesc} |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
732 |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
733 \begin{cvardesc}{int}{Py_single_input} |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
734 The start symbol from the Python grammar for a single statement; for |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
735 use with \cfunction{Py_CompileString()}\ttindex{Py_CompileString()}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
736 This is the symbol used for the interactive interpreter loop. |
|
11222
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
737 \end{cvardesc} |
|
ecfe3d8cb0c3
Clarified start parameter to Py_CompileString, documented
Fred Drake <fdrake@acm.org>
parents:
11176
diff
changeset
|
738 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
739 |
| 10163 | 740 \chapter{Reference Counting \label{countingRefs}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
741 |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
742 The macros in this section are used for managing reference counts |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
743 of Python objects. |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
744 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
745 \begin{cfuncdesc}{void}{Py_INCREF}{PyObject *o} |
| 7782 | 746 Increment the reference count for object \var{o}. The object must |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
747 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use |
| 7308 | 748 \cfunction{Py_XINCREF()}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
749 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
750 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
751 \begin{cfuncdesc}{void}{Py_XINCREF}{PyObject *o} |
| 7308 | 752 Increment the reference count for object \var{o}. The object may be |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
753 \NULL{}, in which case the macro has no effect. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
754 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
755 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
756 \begin{cfuncdesc}{void}{Py_DECREF}{PyObject *o} |
| 7308 | 757 Decrement the reference count for object \var{o}. The object must |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
758 not be \NULL{}; if you aren't sure that it isn't \NULL{}, use |
| 7308 | 759 \cfunction{Py_XDECREF()}. If the reference count reaches zero, the |
| 760 object's type's deallocation function (which must not be \NULL{}) is | |
| 761 invoked. | |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
762 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
763 \strong{Warning:} The deallocation function can cause arbitrary Python |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
764 code to be invoked (e.g. when a class instance with a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
765 \method{__del__()} method is deallocated). While exceptions in such |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
766 code are not propagated, the executed code has free access to all |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
767 Python global variables. This means that any object that is reachable |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
768 from a global variable should be in a consistent state before |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
769 \cfunction{Py_DECREF()} is invoked. For example, code to delete an |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
770 object from a list should copy a reference to the deleted object in a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
771 temporary variable, update the list data structure, and then call |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
772 \cfunction{Py_DECREF()} for the temporary variable. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
773 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
774 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
775 \begin{cfuncdesc}{void}{Py_XDECREF}{PyObject *o} |
| 7308 | 776 Decrement the reference count for object \var{o}. The object may be |
| 777 \NULL{}, in which case the macro has no effect; otherwise the effect | |
| 778 is the same as for \cfunction{Py_DECREF()}, and the same warning | |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
779 applies. |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
780 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
781 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
782 The following functions or macros are only for use within the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
783 interpreter core: \cfunction{_Py_Dealloc()}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
784 \cfunction{_Py_ForgetReference()}, \cfunction{_Py_NewReference()}, as |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
785 well as the global variable \cdata{_Py_RefTotal}. |
|
6653
c6c1d133677a
Several changes, e.g. restructuring of the intro to be closer to what
Guido van Rossum <guido@python.org>
parents:
6480
diff
changeset
|
786 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
787 |
| 10163 | 788 \chapter{Exception Handling \label{exceptionHandling}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
789 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
790 The functions described in this chapter will let you handle and raise Python |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
791 exceptions. It is important to understand some of the basics of |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
792 Python exception handling. It works somewhat like the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
793 \UNIX{} \cdata{errno} variable: there is a global indicator (per |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
794 thread) of the last error that occurred. Most functions don't clear |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
795 this on success, but will set it to indicate the cause of the error on |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
796 failure. Most functions also return an error indicator, usually |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
797 \NULL{} if they are supposed to return a pointer, or \code{-1} if they |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
798 return an integer (exception: the \cfunction{PyArg_Parse*()} functions |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
799 return \code{1} for success and \code{0} for failure). When a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
800 function must fail because some function it called failed, it |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
801 generally doesn't set the error indicator; the function it called |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
802 already set it. |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
803 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
804 The error indicator consists of three Python objects corresponding to |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
805 \withsubitem{(in module sys)}{ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
806 \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
807 the Python variables \code{sys.exc_type}, \code{sys.exc_value} and |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
808 \code{sys.exc_traceback}. API functions exist to interact with the |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
809 error indicator in various ways. There is a separate error indicator |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
810 for each thread. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
811 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
812 % XXX Order of these should be more thoughtful. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
813 % Either alphabetical or some kind of structure. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
814 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
815 \begin{cfuncdesc}{void}{PyErr_Print}{} |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
816 Print a standard traceback to \code{sys.stderr} and clear the error |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
817 indicator. Call this function only when the error indicator is set. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
818 (Otherwise it will cause a fatal error!) |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
819 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
820 |
| 7782 | 821 \begin{cfuncdesc}{PyObject*}{PyErr_Occurred}{} |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
822 Test whether the error indicator is set. If set, return the exception |
| 7308 | 823 \emph{type} (the first argument to the last call to one of the |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
824 \cfunction{PyErr_Set*()} functions or to \cfunction{PyErr_Restore()}). If |
| 7308 | 825 not set, return \NULL{}. You do not own a reference to the return |
| 826 value, so you do not need to \cfunction{Py_DECREF()} it. | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
827 \strong{Note:} Do not compare the return value to a specific |
| 7308 | 828 exception; use \cfunction{PyErr_ExceptionMatches()} instead, shown |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
829 below. (The comparison could easily fail since the exception may be |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
830 an instance instead of a class, in the case of a class exception, or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
831 it may the a subclass of the expected exception.) |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
832 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
833 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
834 \begin{cfuncdesc}{int}{PyErr_ExceptionMatches}{PyObject *exc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
835 Equivalent to |
| 7308 | 836 \samp{PyErr_GivenExceptionMatches(PyErr_Occurred(), \var{exc})}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
837 This should only be called when an exception is actually set; a memory |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
838 access violation will occur if no exception has been raised. |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
839 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
840 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
841 \begin{cfuncdesc}{int}{PyErr_GivenExceptionMatches}{PyObject *given, PyObject *exc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
842 Return true if the \var{given} exception matches the exception in |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
843 \var{exc}. If \var{exc} is a class object, this also returns true |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
844 when \var{given} is an instance of a subclass. If \var{exc} is a tuple, all |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
845 exceptions in the tuple (and recursively in subtuples) are searched |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
846 for a match. If \var{given} is \NULL, a memory access violation will |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
847 occur. |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
848 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
849 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
850 \begin{cfuncdesc}{void}{PyErr_NormalizeException}{PyObject**exc, PyObject**val, PyObject**tb} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
851 Under certain circumstances, the values returned by |
| 7308 | 852 \cfunction{PyErr_Fetch()} below can be ``unnormalized'', meaning that |
| 853 \code{*\var{exc}} is a class object but \code{*\var{val}} is not an | |
| 854 instance of the same class. This function can be used to instantiate | |
| 855 the class in that case. If the values are already normalized, nothing | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
856 happens. The delayed normalization is implemented to improve |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
857 performance. |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
858 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
859 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
860 \begin{cfuncdesc}{void}{PyErr_Clear}{} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
861 Clear the error indicator. If the error indicator is not set, there |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
862 is no effect. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
863 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
864 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
865 \begin{cfuncdesc}{void}{PyErr_Fetch}{PyObject **ptype, PyObject **pvalue, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
866 PyObject **ptraceback} |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
867 Retrieve the error indicator into three variables whose addresses are |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
868 passed. If the error indicator is not set, set all three variables to |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
869 \NULL{}. If it is set, it will be cleared and you own a reference to |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
870 each object retrieved. The value and traceback object may be |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
871 \NULL{} even when the type object is not. \strong{Note:} This |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
872 function is normally only used by code that needs to handle exceptions |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
873 or by code that needs to save and restore the error indicator |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
874 temporarily. |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
875 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
876 |
| 14279 | 877 \begin{cfuncdesc}{void}{PyErr_Restore}{PyObject *type, PyObject *value, |
| 878 PyObject *traceback} | |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
879 Set the error indicator from the three objects. If the error |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
880 indicator is already set, it is cleared first. If the objects are |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
881 \NULL{}, the error indicator is cleared. Do not pass a \NULL{} type |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
882 and non-\NULL{} value or traceback. The exception type should be a |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
883 string or class; if it is a class, the value should be an instance of |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
884 that class. Do not pass an invalid exception type or value. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
885 (Violating these rules will cause subtle problems later.) This call |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
886 takes away a reference to each object: you must own a reference |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
887 to each object before the call and after the call you no longer own |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
888 these references. (If you don't understand this, don't use this |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
889 function. I warned you.) \strong{Note:} This function is normally |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
890 only used by code that needs to save and restore the error indicator |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
891 temporarily. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
892 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
893 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
894 \begin{cfuncdesc}{void}{PyErr_SetString}{PyObject *type, char *message} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
895 This is the most common way to set the error indicator. The first |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
896 argument specifies the exception type; it is normally one of the |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
897 standard exceptions, e.g. \cdata{PyExc_RuntimeError}. You need not |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
898 increment its reference count. The second argument is an error |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
899 message; it is converted to a string object. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
900 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
901 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
902 \begin{cfuncdesc}{void}{PyErr_SetObject}{PyObject *type, PyObject *value} |
| 7308 | 903 This function is similar to \cfunction{PyErr_SetString()} but lets you |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
904 specify an arbitrary Python object for the ``value'' of the exception. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
905 You need not increment its reference count. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
906 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
907 |
|
12355
04802b7e8a1f
Yet another markup nit: functions that are part of the Python/C API
Fred Drake <fdrake@acm.org>
parents:
12354
diff
changeset
|
908 \begin{cfuncdesc}{PyObject*}{PyErr_Format}{PyObject *exception, |
|
14347
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
909 const char *format, \moreargs} |
|
15236
f1ade8ab1869
For PyErr_Format(), note that the exception parameter can be a string or
Fred Drake <fdrake@acm.org>
parents:
15087
diff
changeset
|
910 This function sets the error indicator. \var{exception} should be a |
|
f1ade8ab1869
For PyErr_Format(), note that the exception parameter can be a string or
Fred Drake <fdrake@acm.org>
parents:
15087
diff
changeset
|
911 Python exception (string or class, not an instance). |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
912 \var{format} should be a string, containing format codes, similar to |
|
14347
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
913 \cfunction{printf}. The \code{width.precision} before a format code |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
914 is parsed, but the width part is ignored. |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
915 |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
916 \begin{tableii}{c|l}{character}{Character}{Meaning} |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
917 \lineii{c}{Character, as an \ctype{int} parameter} |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
918 \lineii{d}{Number in decimal, as an \ctype{int} parameter} |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
919 \lineii{x}{Number in hexadecimal, as an \ctype{int} parameter} |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
920 \lineii{x}{A string, as a \ctype{char *} parameter} |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
921 \end{tableii} |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
922 |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
923 An unrecognized format character causes all the rest of |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
924 the format string to be copied as-is to the result string, |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
925 and any extra arguments discarded. |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
926 |
|
2de1fb5302ed
Update documentation for PyErr_Format, because the function has changed.
Moshe Zadka <moshez@math.huji.ac.il>
parents:
14337
diff
changeset
|
927 A new reference is returned, which is owned by the caller. |
|
12353
54e80db49423
document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
12258
diff
changeset
|
928 \end{cfuncdesc} |
|
54e80db49423
document PyErr_Format
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
12258
diff
changeset
|
929 |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
930 \begin{cfuncdesc}{void}{PyErr_SetNone}{PyObject *type} |
| 7308 | 931 This is a shorthand for \samp{PyErr_SetObject(\var{type}, Py_None)}. |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
932 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
933 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
934 \begin{cfuncdesc}{int}{PyErr_BadArgument}{} |
| 7308 | 935 This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
936 \var{message})}, where \var{message} indicates that a built-in operation |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
937 was invoked with an illegal argument. It is mostly for internal use. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
938 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
939 |
| 7782 | 940 \begin{cfuncdesc}{PyObject*}{PyErr_NoMemory}{} |
| 7308 | 941 This is a shorthand for \samp{PyErr_SetNone(PyExc_MemoryError)}; it |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
942 returns \NULL{} so an object allocation function can write |
| 7308 | 943 \samp{return PyErr_NoMemory();} when it runs out of memory. |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
944 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
945 |
| 7782 | 946 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrno}{PyObject *type} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
947 This is a convenience function to raise an exception when a C library |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
948 function has returned an error and set the C variable \cdata{errno}. |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
949 It constructs a tuple object whose first item is the integer |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
950 \cdata{errno} value and whose second item is the corresponding error |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
951 message (gotten from \cfunction{strerror()}\ttindex{strerror()}), and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
952 then calls |
| 7308 | 953 \samp{PyErr_SetObject(\var{type}, \var{object})}. On \UNIX{}, when |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
954 the \cdata{errno} value is \constant{EINTR}, indicating an interrupted |
| 7308 | 955 system call, this calls \cfunction{PyErr_CheckSignals()}, and if that set |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
956 the error indicator, leaves it set to that. The function always |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
957 returns \NULL{}, so a wrapper function around a system call can write |
| 7308 | 958 \samp{return PyErr_SetFromErrno();} when the system call returns an |
| 959 error. | |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
960 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
961 |
|
18192
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
962 \begin{cfuncdesc}{PyObject*}{PyErr_SetFromErrnoWithFilename}{PyObject *type, |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
963 char *filename} |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
964 Similar to \cfunction{PyErr_SetFromErrno()}, with the additional |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
965 behavior that if \var{filename} is not \NULL, it is passed to the |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
966 constructor of \var{type} as a third parameter. In the case of |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
967 exceptions such as \exception{IOError} and \exception{OSError}, this |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
968 is used to define the \member{filename} attribute of the exception |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
969 instance. |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
970 \end{cfuncdesc} |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
971 |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
972 \begin{cfuncdesc}{void}{PyErr_BadInternalCall}{} |
| 7308 | 973 This is a shorthand for \samp{PyErr_SetString(PyExc_TypeError, |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
974 \var{message})}, where \var{message} indicates that an internal |
|
6084
0aa62cbed9f8
Consistently change Python-C API to Python/C API; added lots of new
Guido van Rossum <guido@python.org>
parents:
6074
diff
changeset
|
975 operation (e.g. a Python/C API function) was invoked with an illegal |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
976 argument. It is mostly for internal use. |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
977 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
978 |
|
15613
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
979 \begin{cfuncdesc}{int}{PyErr_Warn}{PyObject *category, char *message} |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
980 Issue a warning message. The \var{category} argument is a warning |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
981 category (see below) or \NULL; the \var{message} argument is a message |
|
15613
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
982 string. |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
983 |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
984 This function normally prints a warning message to \var{sys.stderr}; |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
985 however, it is also possible that the user has specified that warnings |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
986 are to be turned into errors, and in that case this will raise an |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
987 exception. It is also possible that the function raises an exception |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
988 because of a problem with the warning machinery (the implementation |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
989 imports the \module{warnings} module to do the heavy lifting). The |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
990 return value is \code{0} if no exception is raised, or \code{-1} if |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
991 an exception is raised. (It is not possible to determine whether a |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
992 warning message is actually printed, nor what the reason is for the |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
993 exception; this is intentional.) If an exception is raised, the |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
994 caller should do its normal exception handling |
|
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
995 (e.g. \cfunction{Py_DECREF()} owned references and return an error |
|
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
996 value). |
|
15613
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
997 |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
998 Warning categories must be subclasses of \cdata{Warning}; the default |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
999 warning category is \cdata{RuntimeWarning}. The standard Python |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1000 warning categories are available as global variables whose names are |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1001 \samp{PyExc_} followed by the Python exception name. These have the |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1002 type \ctype{PyObject*}; they are all class objects. Their names are |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1003 \cdata{PyExc_Warning}, \cdata{PyExc_UserWarning}, |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1004 \cdata{PyExc_DeprecationWarning}, \cdata{PyExc_SyntaxWarning}, and |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1005 \cdata{PyExc_RuntimeWarning}. \cdata{PyExc_Warning} is a subclass of |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1006 \cdata{PyExc_Exception}; the other warning categories are subclasses |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1007 of \cdata{PyExc_Warning}. |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1008 |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1009 For information about warning control, see the documentation for the |
|
15733
00c6855d742a
Markup nit: Command line options should be marked with \programopt.
Fred Drake <fdrake@acm.org>
parents:
15613
diff
changeset
|
1010 \module{warnings} module and the \programopt{-W} option in the command |
|
00c6855d742a
Markup nit: Command line options should be marked with \programopt.
Fred Drake <fdrake@acm.org>
parents:
15613
diff
changeset
|
1011 line documentation. There is no C API for warning control. |
|
15613
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1012 \end{cfuncdesc} |
|
35749a557f1e
Document Pyerr_Warn().
Guido van Rossum <guido@python.org>
parents:
15453
diff
changeset
|
1013 |
|
16872
5280e8439d55
Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents:
16577
diff
changeset
|
1014 \begin{cfuncdesc}{int}{PyErr_WarnExplicit}{PyObject *category, char *message, |
|
5280e8439d55
Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents:
16577
diff
changeset
|
1015 char *filename, int lineno, char *module, PyObject *registry} |
|
5280e8439d55
Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents:
16577
diff
changeset
|
1016 Issue a warning message with explicit control over all warning |
|
5280e8439d55
Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents:
16577
diff
changeset
|
1017 attributes. This is a straightforward wrapper around the Python |
|
5280e8439d55
Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents:
16577
diff
changeset
|
1018 function \function{warnings.warn_explicit()}, see there for more |
|
5280e8439d55
Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents:
16577
diff
changeset
|
1019 information. The \var{module} and \var{registry} arguments may be |
|
5280e8439d55
Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents:
16577
diff
changeset
|
1020 set to \code{NULL} to get the default effect described there. |
|
5280e8439d55
Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents:
16577
diff
changeset
|
1021 \end{cfuncdesc} |
|
5280e8439d55
Document PyErr_WarnExplicit().
Guido van Rossum <guido@python.org>
parents:
16577
diff
changeset
|
1022 |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1023 \begin{cfuncdesc}{int}{PyErr_CheckSignals}{} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1024 This function interacts with Python's signal handling. It checks |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1025 whether a signal has been sent to the processes and if so, invokes the |
|
7310
6095a472f574
Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents:
7309
diff
changeset
|
1026 corresponding signal handler. If the |
|
6095a472f574
Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents:
7309
diff
changeset
|
1027 \module{signal}\refbimodindex{signal} module is supported, this can |
|
6095a472f574
Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents:
7309
diff
changeset
|
1028 invoke a signal handler written in Python. In all cases, the default |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1029 effect for \constant{SIGINT}\ttindex{SIGINT} is to raise the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1030 \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1031 \exception{KeyboardInterrupt} exception. If an exception is raised the |
| 7308 | 1032 error indicator is set and the function returns \code{1}; otherwise |
| 1033 the function returns \code{0}. The error indicator may or may not be | |
| 1034 cleared if it was previously set. | |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1035 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1036 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1037 \begin{cfuncdesc}{void}{PyErr_SetInterrupt}{} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1038 This function is obsolete. It simulates the effect of a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1039 \constant{SIGINT}\ttindex{SIGINT} signal arriving --- the next time |
| 7308 | 1040 \cfunction{PyErr_CheckSignals()} is called, |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1041 \withsubitem{(built-in exception)}{\ttindex{KeyboardInterrupt}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1042 \exception{KeyboardInterrupt} will be raised. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1043 It may be called without holding the interpreter lock. |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1044 \end{cfuncdesc} |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1045 |
| 7782 | 1046 \begin{cfuncdesc}{PyObject*}{PyErr_NewException}{char *name, |
| 1047 PyObject *base, | |
| 1048 PyObject *dict} | |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1049 This utility function creates and returns a new exception object. The |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1050 \var{name} argument must be the name of the new exception, a C string |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1051 of the form \code{module.class}. The \var{base} and |
|
13150
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1052 \var{dict} arguments are normally \NULL{}. This creates a |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1053 class object derived from the root for all exceptions, the built-in |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1054 name \exception{Exception} (accessible in C as |
|
13150
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1055 \cdata{PyExc_Exception}). The \member{__module__} attribute of the |
|
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1056 new class is set to the first part (up to the last dot) of the |
|
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1057 \var{name} argument, and the class name is set to the last part (after |
|
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1058 the last dot). The \var{base} argument can be used to specify an |
|
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1059 alternate base class. The \var{dict} argument can be used to specify |
|
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1060 a dictionary of class variables and methods. |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1061 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1062 |
|
14330
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1063 \begin{cfuncdesc}{void}{PyErr_WriteUnraisable}{PyObject *obj} |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1064 This utility function prints a warning message to \var{sys.stderr} |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1065 when an exception has been set but it is impossible for the |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1066 interpreter to actually raise the exception. It is used, for example, |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1067 when an exception occurs in an \member{__del__} method. |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1068 |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1069 The function is called with a single argument \var{obj} that |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1070 identifies where the context in which the unraisable exception |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1071 occurred. The repr of \var{obj} will be printed in the warning |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1072 message. |
|
6dee1985c681
refactor __del__ exception handler into PyErr_WriteUnraisable
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
14279
diff
changeset
|
1073 \end{cfuncdesc} |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1074 |
| 10163 | 1075 \section{Standard Exceptions \label{standardExceptions}} |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1076 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1077 All standard Python exceptions are available as global variables whose |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1078 names are \samp{PyExc_} followed by the Python exception name. These |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1079 have the type \ctype{PyObject*}; they are all class objects. For |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1080 completeness, here are all the variables: |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1081 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1082 \begin{tableiii}{l|l|c}{cdata}{C Name}{Python Name}{Notes} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1083 \lineiii{PyExc_Exception}{\exception{Exception}}{(1)} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1084 \lineiii{PyExc_StandardError}{\exception{StandardError}}{(1)} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1085 \lineiii{PyExc_ArithmeticError}{\exception{ArithmeticError}}{(1)} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1086 \lineiii{PyExc_LookupError}{\exception{LookupError}}{(1)} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1087 \lineiii{PyExc_AssertionError}{\exception{AssertionError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1088 \lineiii{PyExc_AttributeError}{\exception{AttributeError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1089 \lineiii{PyExc_EOFError}{\exception{EOFError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1090 \lineiii{PyExc_EnvironmentError}{\exception{EnvironmentError}}{(1)} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1091 \lineiii{PyExc_FloatingPointError}{\exception{FloatingPointError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1092 \lineiii{PyExc_IOError}{\exception{IOError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1093 \lineiii{PyExc_ImportError}{\exception{ImportError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1094 \lineiii{PyExc_IndexError}{\exception{IndexError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1095 \lineiii{PyExc_KeyError}{\exception{KeyError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1096 \lineiii{PyExc_KeyboardInterrupt}{\exception{KeyboardInterrupt}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1097 \lineiii{PyExc_MemoryError}{\exception{MemoryError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1098 \lineiii{PyExc_NameError}{\exception{NameError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1099 \lineiii{PyExc_NotImplementedError}{\exception{NotImplementedError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1100 \lineiii{PyExc_OSError}{\exception{OSError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1101 \lineiii{PyExc_OverflowError}{\exception{OverflowError}}{} |
|
20286
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
1102 \lineiii{PyExc_ReferenceError}{\exception{ReferenceError}}{(2)} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1103 \lineiii{PyExc_RuntimeError}{\exception{RuntimeError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1104 \lineiii{PyExc_SyntaxError}{\exception{SyntaxError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1105 \lineiii{PyExc_SystemError}{\exception{SystemError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1106 \lineiii{PyExc_SystemExit}{\exception{SystemExit}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1107 \lineiii{PyExc_TypeError}{\exception{TypeError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1108 \lineiii{PyExc_ValueError}{\exception{ValueError}}{} |
|
20286
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
1109 \lineiii{PyExc_WindowsError}{\exception{WindowsError}}{(3)} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1110 \lineiii{PyExc_ZeroDivisionError}{\exception{ZeroDivisionError}}{} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1111 \end{tableiii} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1112 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1113 \noindent |
| 13929 | 1114 Notes: |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1115 \begin{description} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1116 \item[(1)] |
|
13150
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1117 This is a base class for other standard exceptions. |
| 13929 | 1118 |
| 1119 \item[(2)] | |
|
20286
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
1120 This is the same as \exception{weakref.ReferenceError}. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
1121 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
1122 \item[(3)] |
| 13929 | 1123 Only defined on Windows; protect code that uses this by testing that |
| 1124 the preprocessor macro \code{MS_WINDOWS} is defined. | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1125 \end{description} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1126 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1127 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1128 \section{Deprecation of String Exceptions} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1129 |
|
13150
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1130 All exceptions built into Python or provided in the standard library |
|
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1131 are derived from \exception{Exception}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1132 \withsubitem{(built-in exception)}{\ttindex{Exception}} |
|
13150
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1133 |
|
f1f4d822e761
Update comments relating to the removal of the -X option and of string
Fred Drake <fdrake@acm.org>
parents:
13053
diff
changeset
|
1134 String exceptions are still supported in the interpreter to allow |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1135 existing code to run unmodified, but this will also change in a future |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1136 release. |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
1137 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1138 |
| 10163 | 1139 \chapter{Utilities \label{utilities}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1140 |
|
18785
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1141 The functions in this chapter perform various utility tasks, ranging |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1142 from helping C code be more portable across platforms, using Python |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1143 modules from C, and parsing function arguments and constructing Python |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1144 values from C values. |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1145 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1146 |
|
18575
670464c94b92
Fix the markup of the caret charater in a couple of places; LaTeX's
Fred Drake <fdrake@acm.org>
parents:
18481
diff
changeset
|
1147 \section{Operating System Utilities \label{os}} |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1148 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1149 \begin{cfuncdesc}{int}{Py_FdIsInteractive}{FILE *fp, char *filename} |
| 7308 | 1150 Return true (nonzero) if the standard I/O file \var{fp} with name |
| 1151 \var{filename} is deemed interactive. This is the case for files for | |
| 1152 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
|
1153 \cdata{Py_InteractiveFlag} is true, this function also returns true if |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
1154 the \var{filename} pointer is \NULL{} or if the name is equal to one of |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
1155 the strings \code{'<stdin>'} or \code{'???'}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1156 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1157 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1158 \begin{cfuncdesc}{long}{PyOS_GetLastModificationTime}{char *filename} |
| 7308 | 1159 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
|
1160 The result is encoded in the same way as the timestamp returned by |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1161 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
|
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 |
|
13053
b00744237877
Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents:
12947
diff
changeset
|
1164 \begin{cfuncdesc}{void}{PyOS_AfterFork}{} |
|
b00744237877
Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents:
12947
diff
changeset
|
1165 Function to update some internal state after a process fork; this |
|
b00744237877
Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents:
12947
diff
changeset
|
1166 should be called in the new process if the Python interpreter will |
|
b00744237877
Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents:
12947
diff
changeset
|
1167 continue to be used. If a new executable is loaded into the new |
|
b00744237877
Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents:
12947
diff
changeset
|
1168 process, this function does not need to be called. |
|
b00744237877
Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents:
12947
diff
changeset
|
1169 \end{cfuncdesc} |
|
b00744237877
Added documentation for PyOS_AfterFork().
Fred Drake <fdrake@acm.org>
parents:
12947
diff
changeset
|
1170 |
| 14279 | 1171 \begin{cfuncdesc}{int}{PyOS_CheckStack}{} |
| 1172 Return true when the interpreter runs out of stack space. This is a | |
| 1173 reliable check, but is only available when \code{USE_STACKCHECK} is | |
| 1174 defined (currently on Windows using the Microsoft Visual C++ compiler | |
| 1175 and on the Macintosh). \code{USE_CHECKSTACK} will be defined | |
| 1176 automatically; you should never change the definition in your own | |
| 1177 code. | |
| 1178 \end{cfuncdesc} | |
| 1179 | |
|
14635
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1180 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_getsig}{int i} |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1181 Return the current signal handler for signal \var{i}. |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1182 This is a thin wrapper around either \cfunction{sigaction} or |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1183 \cfunction{signal}. Do not call those functions directly! |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1184 \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}. |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1185 \end{cfuncdesc} |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1186 |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1187 \begin{cfuncdesc}{PyOS_sighandler_t}{PyOS_setsig}{int i, PyOS_sighandler_t h} |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1188 Set the signal handler for signal \var{i} to be \var{h}; |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1189 return the old signal handler. |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1190 This is a thin wrapper around either \cfunction{sigaction} or |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1191 \cfunction{signal}. Do not call those functions directly! |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1192 \ctype{PyOS_sighandler_t} is a typedef alias for \ctype{void (*)(int)}. |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1193 \end{cfuncdesc} |
|
db9ea5b5f337
Document new APIs PyOS_getsig() and PyOS_setsig().
Guido van Rossum <guido@python.org>
parents:
14557
diff
changeset
|
1194 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1195 |
| 10163 | 1196 \section{Process Control \label{processControl}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1197 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1198 \begin{cfuncdesc}{void}{Py_FatalError}{char *message} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1199 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
|
1200 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
|
1201 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
|
1202 interpreter; e.g., when the object administration appears to be |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1203 corrupted. On \UNIX{}, the standard C library function |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1204 \cfunction{abort()}\ttindex{abort()} is called which will attempt to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1205 produce a \file{core} file. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1206 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1207 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1208 \begin{cfuncdesc}{void}{Py_Exit}{int status} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1209 Exit the current process. This calls |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1210 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1211 then calls the standard C library function |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1212 \code{exit(\var{status})}\ttindex{exit()}. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1213 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1214 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1215 \begin{cfuncdesc}{int}{Py_AtExit}{void (*func) ()} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1216 Register a cleanup function to be called by |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1217 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()}. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1218 The cleanup function will be called with no arguments and should |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1219 return no value. At most 32 \index{cleanup functions}cleanup |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1220 functions can be registered. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1221 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
|
1222 \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
|
1223 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
|
1224 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
|
1225 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
|
1226 by \var{func}. |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1227 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1228 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
1229 |
| 10163 | 1230 \section{Importing Modules \label{importing}} |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1231 |
| 7782 | 1232 \begin{cfuncdesc}{PyObject*}{PyImport_ImportModule}{char *name} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1233 This is a simplified interface to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1234 \cfunction{PyImport_ImportModuleEx()} below, leaving the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1235 \var{globals} and \var{locals} arguments set to \NULL{}. When the |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
1236 \var{name} argument contains a dot (when it specifies a |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1237 submodule of a package), the \var{fromlist} argument is set to the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1238 list \code{['*']} so that the return value is the named module rather |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1239 than the top-level package containing it as would otherwise be the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1240 case. (Unfortunately, this has an additional side effect when |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1241 \var{name} in fact specifies a subpackage instead of a submodule: the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1242 submodules specified in the package's \code{__all__} variable are |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1243 \index{package variable!\code{__all__}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1244 \withsubitem{(package variable)}{\ttindex{__all__}}loaded.) Return a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1245 new reference to the imported module, or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1246 \NULL{} with an exception set on failure (the module may still be |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1247 created in this case --- examine \code{sys.modules} to find out). |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1248 \withsubitem{(in module sys)}{\ttindex{modules}} |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1249 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1250 |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1251 \begin{cfuncdesc}{PyObject*}{PyImport_ImportModuleEx}{char *name, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1252 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
|
1253 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
|
1254 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
|
1255 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
|
1256 directly. |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1257 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1258 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
|
1259 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
|
1260 (the module may still be created in this case). Like for |
| 7308 | 1261 \function{__import__()}, the return value when a submodule of a |
| 1262 package was requested is normally the top-level package, unless a | |
| 1263 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
|
1264 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1265 |
| 7782 | 1266 \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
|
1267 This is a higher-level interface that calls the current ``import hook |
| 7308 | 1268 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
|
1269 \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
|
1270 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
|
1271 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
|
1272 \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
|
1273 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1274 |
| 7782 | 1275 \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
|
1276 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
|
1277 Python function \function{reload()}\bifuncindex{reload}, as the standard |
| 7308 | 1278 \function{reload()} function calls this function directly. Return a |
| 1279 new reference to the reloaded module, or \NULL{} with an exception set | |
| 1280 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
|
1281 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1282 |
| 7782 | 1283 \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
|
1284 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
|
1285 \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
|
1286 check the modules dictionary if there's one there, and if not, create |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1287 a new one and insert in in the modules dictionary. |
|
9476
1ea6d2356e52
Warn that AddModule doesn't import the module.
Guido van Rossum <guido@python.org>
parents:
9383
diff
changeset
|
1288 Warning: this function does not load or import the module; if the |
|
1ea6d2356e52
Warn that AddModule doesn't import the module.
Guido van Rossum <guido@python.org>
parents:
9383
diff
changeset
|
1289 module wasn't already loaded, you will get an empty module object. |
|
1ea6d2356e52
Warn that AddModule doesn't import the module.
Guido van Rossum <guido@python.org>
parents:
9383
diff
changeset
|
1290 Use \cfunction{PyImport_ImportModule()} or one of its variants to |
|
1ea6d2356e52
Warn that AddModule doesn't import the module.
Guido van Rossum <guido@python.org>
parents:
9383
diff
changeset
|
1291 import a module. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1292 Return \NULL{} with an exception set on failure. |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1293 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1294 |
| 7782 | 1295 \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
|
1296 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
|
1297 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
|
1298 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
|
1299 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
|
1300 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
|
1301 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
|
1302 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
|
1303 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1304 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1305 \begin{cfuncdesc}{long}{PyImport_GetMagicNumber}{} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1306 Return the magic number for Python bytecode files (a.k.a. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1307 \file{.pyc} and \file{.pyo} files). The magic number should be |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1308 present in the first four bytes of the bytecode file, in little-endian |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1309 byte order. |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1310 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1311 |
| 7782 | 1312 \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
|
1313 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
|
1314 (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
|
1315 variable. |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1316 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1317 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1318 \begin{cfuncdesc}{void}{_PyImport_Init}{} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1319 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
|
1320 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1321 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1322 \begin{cfuncdesc}{void}{PyImport_Cleanup}{} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1323 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
|
1324 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1325 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1326 \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
|
1327 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
|
1328 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1329 |
| 7782 | 1330 \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
|
1331 For internal use only. |
|
6991
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
1332 \end{cfuncdesc} |
|
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
1333 |
| 7782 | 1334 \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
|
1335 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
|
1336 \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
|
1337 |
| 12947 | 1338 \begin{cfuncdesc}{int}{PyImport_ImportFrozenModule}{char *name} |
| 1339 Load a frozen module named \var{name}. Return \code{1} for success, | |
| 1340 \code{0} if the module is not found, and \code{-1} with an exception | |
| 1341 set if the initialization failed. To access the imported module on a | |
| 1342 successful load, use \cfunction{PyImport_ImportModule()}. | |
| 7308 | 1343 (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
|
1344 already imported.) |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1345 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1346 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1347 \begin{ctypedesc}[_frozen]{struct _frozen} |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1348 This is the structure type definition for frozen module descriptors, |
| 7782 | 1349 as generated by the \program{freeze}\index{freeze utility} utility |
| 1350 (see \file{Tools/freeze/} in the Python source distribution). Its | |
|
14337
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1351 definition, found in \file{Include/import.h}, is: |
| 7782 | 1352 |
|
6417
4491f84ac223
Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents:
6390
diff
changeset
|
1353 \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
|
1354 struct _frozen { |
| 6480 | 1355 char *name; |
| 1356 unsigned char *code; | |
| 1357 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
|
1358 }; |
|
6417
4491f84ac223
Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents:
6390
diff
changeset
|
1359 \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
|
1360 \end{ctypedesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1361 |
| 7782 | 1362 \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
|
1363 This pointer is initialized to point to an array of \ctype{struct |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1364 _frozen} records, terminated by one whose members are all |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1365 \NULL{} or zero. When a frozen module is imported, it is searched in |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1366 this table. Third-party code could play tricks with this to provide a |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1367 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
|
1368 \end{cvardesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1369 |
|
14337
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1370 \begin{cfuncdesc}{int}{PyImport_AppendInittab}{char *name, |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1371 void (*initfunc)(void)} |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1372 Add a single module to the existing table of built-in modules. This |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1373 is a convenience wrapper around \cfunction{PyImport_ExtendInittab()}, |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1374 returning \code{-1} if the table could not be extended. The new |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1375 module can be imported by the name \var{name}, and uses the function |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1376 \var{initfunc} as the initialization function called on the first |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1377 attempted import. This should be called before |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1378 \cfunction{Py_Initialize()}. |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1379 \end{cfuncdesc} |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1380 |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1381 \begin{ctypedesc}[_inittab]{struct _inittab} |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1382 Structure describing a single entry in the list of built-in modules. |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1383 Each of these structures gives the name and initialization function |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1384 for a module built into the interpreter. Programs which embed Python |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1385 may use an array of these structures in conjunction with |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1386 \cfunction{PyImport_ExtendInittab()} to provide additional built-in |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1387 modules. The structure is defined in \file{Include/import.h} as: |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1388 |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1389 \begin{verbatim} |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1390 struct _inittab { |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1391 char *name; |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1392 void (*initfunc)(void); |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1393 }; |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1394 \end{verbatim} |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1395 \end{ctypedesc} |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1396 |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1397 \begin{cfuncdesc}{int}{PyImport_ExtendInittab}{struct _inittab *newtab} |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1398 Add a collection of modules to the table of built-in modules. The |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1399 \var{newtab} array must end with a sentinel entry which contains |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1400 \NULL{} for the \member{name} field; failure to provide the sentinel |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1401 value can result in a memory fault. Returns \code{0} on success or |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1402 \code{-1} if insufficient memory could be allocated to extend the |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1403 internal table. In the event of failure, no modules are added to the |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1404 internal table. This should be called before |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1405 \cfunction{Py_Initialize()}. |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1406 \end{cfuncdesc} |
|
3b84c5ff89da
Document PyImport_AppendInittab(), PyImport_ExtendInittab(), and
Fred Drake <fdrake@acm.org>
parents:
14330
diff
changeset
|
1407 |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
1408 |
| 20111 | 1409 \section{Parsing arguments and building values |
|
18785
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1410 \label{arg-parsing}} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1411 |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1412 These functions are useful when creating your own extensions functions |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1413 and methods. Additional information and examples are available in |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1414 \citetitle[../ext/ext.html]{Extending and Embedding the Python |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1415 Interpreter}. |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1416 |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1417 \begin{cfuncdesc}{int}{PyArg_ParseTuple}{PyObject *args, char *format, |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1418 \moreargs} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1419 Parse the parameters of a function that takes only positional |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1420 parameters into local variables. Returns true on success; on |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1421 failure, it returns false and raises the appropriate exception. See |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1422 \citetitle[../ext/parseTuple.html]{Extending and Embedding the |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1423 Python Interpreter} for more information. |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1424 \end{cfuncdesc} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1425 |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1426 \begin{cfuncdesc}{int}{PyArg_ParseTupleAndKeywords}{PyObject *args, |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1427 PyObject *kw, char *format, char *keywords[], |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1428 \moreargs} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1429 Parse the parameters of a function that takes both positional and |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1430 keyword parameters into local variables. Returns true on success; |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1431 on failure, it returns false and raises the appropriate exception. |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1432 See \citetitle[../ext/parseTupleAndKeywords.html]{Extending and |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1433 Embedding the Python Interpreter} for more information. |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1434 \end{cfuncdesc} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1435 |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1436 \begin{cfuncdesc}{int}{PyArg_Parse}{PyObject *args, char *format, |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1437 \moreargs} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1438 Function used to deconstruct the argument lists of ``old-style'' |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1439 functions --- these are functions which use the |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1440 \constant{METH_OLDARGS} parameter parsing method. This is not |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1441 recommended for use in parameter parsing in new code, and most code |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1442 in the standard interpreter has been modified to no longer use this |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1443 for that purpose. It does remain a convenient way to decompose |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1444 other tuples, however, and may continue to be used for that |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1445 purpose. |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1446 \end{cfuncdesc} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1447 |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1448 \begin{cfuncdesc}{PyObject*}{Py_BuildValue}{char *format, |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1449 \moreargs} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1450 Create a new value based on a format string similar to those |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1451 accepted by the \cfunction{PyArg_Parse*()} family of functions and a |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1452 sequence of values. Returns the value or \NULL{} in the case of an |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1453 error; an exception will be raised if \NULL{} is returned. For more |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1454 information on the format string and additional parameters, see |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1455 \citetitle[../ext/buildValue.html]{Extending and Embedding the |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1456 Python Interpreter}. |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1457 \end{cfuncdesc} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1458 |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1459 |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
1460 |
| 10163 | 1461 \chapter{Abstract Objects Layer \label{abstract}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1462 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1463 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
|
1464 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
|
1465 numerical types, or all sequence types). When used on object types |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1466 for which they do not apply, they will raise a Python exception. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1467 |
| 10163 | 1468 \section{Object Protocol \label{object}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1469 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1470 \begin{cfuncdesc}{int}{PyObject_Print}{PyObject *o, FILE *fp, int flags} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1471 Print an object \var{o}, on file \var{fp}. Returns \code{-1} on error. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1472 The flags argument is used to enable certain printing options. The |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1473 only option currently supported is \constant{Py_PRINT_RAW}; if given, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1474 the \function{str()} of the object is written instead of the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1475 \function{repr()}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1476 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1477 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1478 \begin{cfuncdesc}{int}{PyObject_HasAttrString}{PyObject *o, char *attr_name} |
| 7308 | 1479 Returns \code{1} if \var{o} has the attribute \var{attr_name}, and |
| 1480 \code{0} otherwise. This is equivalent to the Python expression | |
| 1481 \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
|
1482 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
|
1483 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1484 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1485 \begin{cfuncdesc}{PyObject*}{PyObject_GetAttrString}{PyObject *o, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1486 char *attr_name} |
| 7308 | 1487 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
|
1488 Returns the attribute value on success, or \NULL{} on failure. |
| 7308 | 1489 This is the equivalent of the Python expression |
| 1490 \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
|
1491 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1492 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1493 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1494 \begin{cfuncdesc}{int}{PyObject_HasAttr}{PyObject *o, PyObject *attr_name} |
| 7308 | 1495 Returns \code{1} if \var{o} has the attribute \var{attr_name}, and |
| 1496 \code{0} otherwise. This is equivalent to the Python expression | |
| 1497 \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
|
1498 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
|
1499 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1500 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1501 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1502 \begin{cfuncdesc}{PyObject*}{PyObject_GetAttr}{PyObject *o, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1503 PyObject *attr_name} |
| 7308 | 1504 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
|
1505 Returns the attribute value on success, or \NULL{} on failure. |
| 7308 | 1506 This is the equivalent of the Python expression |
| 1507 \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
|
1508 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1509 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1510 |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1511 \begin{cfuncdesc}{int}{PyObject_SetAttrString}{PyObject *o, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1512 char *attr_name, PyObject *v} |
| 7308 | 1513 Set the value of the attribute named \var{attr_name}, for object |
| 1514 \var{o}, to the value \var{v}. Returns \code{-1} on failure. This is | |
| 1515 the equivalent of the Python statement \samp{\var{o}.\var{attr_name} = | |
| 1516 \var{v}}. | |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1517 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1518 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1519 |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1520 \begin{cfuncdesc}{int}{PyObject_SetAttr}{PyObject *o, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1521 PyObject *attr_name, PyObject *v} |
| 7308 | 1522 Set the value of the attribute named \var{attr_name}, for |
| 1523 object \var{o}, | |
| 1524 to the value \var{v}. Returns \code{-1} on failure. This is | |
| 1525 the equivalent of the Python statement \samp{\var{o}.\var{attr_name} = | |
| 1526 \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
|
1527 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1528 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1529 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1530 \begin{cfuncdesc}{int}{PyObject_DelAttrString}{PyObject *o, char *attr_name} |
| 7308 | 1531 Delete attribute named \var{attr_name}, for object \var{o}. Returns |
| 1532 \code{-1} on failure. This is the equivalent of the Python | |
| 1533 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
|
1534 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1535 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1536 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1537 \begin{cfuncdesc}{int}{PyObject_DelAttr}{PyObject *o, PyObject *attr_name} |
| 7308 | 1538 Delete attribute named \var{attr_name}, for object \var{o}. Returns |
| 1539 \code{-1} on failure. This is the equivalent of the Python | |
| 1540 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
|
1541 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1542 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1543 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1544 \begin{cfuncdesc}{int}{PyObject_Cmp}{PyObject *o1, PyObject *o2, int *result} |
| 7308 | 1545 Compare the values of \var{o1} and \var{o2} using a routine provided |
| 1546 by \var{o1}, if one exists, otherwise with a routine provided by | |
| 1547 \var{o2}. The result of the comparison is returned in \var{result}. | |
| 1548 Returns \code{-1} on failure. This is the equivalent of the Python | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1549 statement\bifuncindex{cmp} \samp{\var{result} = cmp(\var{o1}, \var{o2})}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1550 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1551 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1552 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1553 \begin{cfuncdesc}{int}{PyObject_Compare}{PyObject *o1, PyObject *o2} |
| 7308 | 1554 Compare the values of \var{o1} and \var{o2} using a routine provided |
| 1555 by \var{o1}, if one exists, otherwise with a routine provided by | |
| 1556 \var{o2}. Returns the result of the comparison on success. On error, | |
| 1557 the value returned is undefined; use \cfunction{PyErr_Occurred()} to | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1558 detect an error. This is equivalent to the Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1559 expression\bifuncindex{cmp} \samp{cmp(\var{o1}, \var{o2})}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1560 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1561 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1562 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1563 \begin{cfuncdesc}{PyObject*}{PyObject_Repr}{PyObject *o} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1564 Compute a string representation of object \var{o}. Returns the |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1565 string representation on success, \NULL{} on failure. This is |
| 7308 | 1566 the equivalent of the Python expression \samp{repr(\var{o})}. |
| 1567 Called by the \function{repr()}\bifuncindex{repr} built-in function | |
| 1568 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
|
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*}{PyObject_Str}{PyObject *o} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1573 Compute a string representation of object \var{o}. Returns the |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1574 string representation on success, \NULL{} on failure. This is |
| 7308 | 1575 the equivalent of the Python expression \samp{str(\var{o})}. |
| 1576 Called by the \function{str()}\bifuncindex{str} built-in function and | |
| 1577 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
|
1578 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1579 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1580 |
|
15952
1f92d63b20f0
This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents:
15733
diff
changeset
|
1581 \begin{cfuncdesc}{PyObject*}{PyObject_Unicode}{PyObject *o} |
|
1f92d63b20f0
This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents:
15733
diff
changeset
|
1582 Compute a Unicode string representation of object \var{o}. Returns the |
|
1f92d63b20f0
This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents:
15733
diff
changeset
|
1583 Unicode string representation on success, \NULL{} on failure. This is |
|
1f92d63b20f0
This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents:
15733
diff
changeset
|
1584 the equivalent of the Python expression \samp{unistr(\var{o})}. |
|
1f92d63b20f0
This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents:
15733
diff
changeset
|
1585 Called by the \function{unistr()}\bifuncindex{unistr} built-in function. |
|
1f92d63b20f0
This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents:
15733
diff
changeset
|
1586 \end{cfuncdesc} |
|
1f92d63b20f0
This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents:
15733
diff
changeset
|
1587 |
|
17242
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1588 \begin{cfuncdesc}{int}{PyObject_IsInstance}{PyObject *inst, PyObject *cls} |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1589 Return \code{1} if \var{inst} is an instance of the class \var{cls} or |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1590 a subclass of \var{cls}. If \var{cls} is a type object rather than a |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1591 class object, \cfunction{PyObject_IsInstance()} returns \code{1} if |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1592 \var{inst} is of type \var{cls}. If \var{inst} is not a class |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1593 instance and \var{cls} is neither a type object or class object, |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1594 \var{inst} must have a \member{__class__} attribute --- the class |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1595 relationship of the value of that attribute with \var{cls} will be |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1596 used to determine the result of this function. |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1597 \versionadded{2.1} |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1598 \end{cfuncdesc} |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1599 |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1600 Subclass determination is done in a fairly straightforward way, but |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1601 includes a wrinkle that implementors of extensions to the class system |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1602 may want to be aware of. If \class{A} and \class{B} are class |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1603 objects, \class{B} is a subclass of \class{A} if it inherits from |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1604 \class{A} either directly or indirectly. If either is not a class |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1605 object, a more general mechanism is used to determine the class |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1606 relationship of the two objects. When testing if \var{B} is a |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1607 subclass of \var{A}, if \var{A} is \var{B}, |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1608 \cfunction{PyObject_IsSubclass()} returns true. If \var{A} and |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1609 \var{B} are different objects, \var{B}'s \member{__bases__} attribute |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1610 is searched in a depth-first fashion for \var{A} --- the presence of |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1611 the \member{__bases__} attribute is considered sufficient for this |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1612 determination. |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1613 |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1614 \begin{cfuncdesc}{int}{PyObject_IsSubclass}{PyObject *derived, |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1615 PyObject *cls} |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1616 Returns \code{1} if the class \var{derived} is identical to or derived |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1617 from the class \var{cls}, otherwise returns \code{0}. In case of an |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1618 error, returns \code{-1}. If either \var{derived} or \var{cls} is not |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1619 an actual class object, this function uses the generic algorithm |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1620 described above. |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1621 \versionadded{2.1} |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1622 \end{cfuncdesc} |
|
1b12e6340038
Added documentation for PyObject_IsInstance() and PyObject_IsSubclass().
Fred Drake <fdrake@acm.org>
parents:
17209
diff
changeset
|
1623 |
|
15952
1f92d63b20f0
This patch adds a new builtin unistr() which behaves like str()
Marc-André Lemburg <mal@egenix.com>
parents:
15733
diff
changeset
|
1624 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1625 \begin{cfuncdesc}{int}{PyCallable_Check}{PyObject *o} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1626 Determine if the object \var{o} is callable. Return \code{1} if the |
| 7308 | 1627 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
|
1628 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
|
1629 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1630 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1631 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1632 \begin{cfuncdesc}{PyObject*}{PyObject_CallObject}{PyObject *callable_object, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1633 PyObject *args} |
| 7308 | 1634 Call a callable Python object \var{callable_object}, with |
| 1635 arguments given by the tuple \var{args}. If no arguments are | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1636 needed, then \var{args} may be \NULL{}. Returns the result of the |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1637 call on success, or \NULL{} on failure. This is the equivalent |
|
18944
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
1638 of the Python expression \samp{apply(\var{callable_object}, |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
1639 \var{args})} or \samp{\var{callable_object}(*\var{args})}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1640 \bifuncindex{apply} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1641 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1642 |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
1643 \begin{cfuncdesc}{PyObject*}{PyObject_CallFunction}{PyObject *callable_object, |
|
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
1644 char *format, ...} |
| 7308 | 1645 Call a callable Python object \var{callable_object}, with a |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1646 variable number of C arguments. The C arguments are described |
| 7308 | 1647 using a \cfunction{Py_BuildValue()} style format string. The format may |
| 1648 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
|
1649 result of the call on success, or \NULL{} on failure. This is |
|
18944
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
1650 the equivalent of the Python expression |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
1651 \samp{apply(\var{callable_object}\var{args})} or |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
1652 \samp{\var{callable_object}(*\var{args})}. |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
1653 \bifuncindex{apply} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1654 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1655 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1656 |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
1657 \begin{cfuncdesc}{PyObject*}{PyObject_CallMethod}{PyObject *o, |
|
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
1658 char *method, char *format, ...} |
| 7308 | 1659 Call the method named \var{m} of object \var{o} with a variable number |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1660 of C arguments. The C arguments are described by a |
| 7308 | 1661 \cfunction{Py_BuildValue()} format string. The format may be \NULL{}, |
| 1662 indicating that no arguments are provided. Returns the result of the | |
| 1663 call on success, or \NULL{} on failure. This is the equivalent of the | |
| 1664 Python expression \samp{\var{o}.\var{method}(\var{args})}. | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1665 Note that special method names, such as \method{__add__()}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1666 \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
|
1667 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
|
1668 \end{cfuncdesc} |
|
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 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1671 \begin{cfuncdesc}{int}{PyObject_Hash}{PyObject *o} |
| 7308 | 1672 Compute and return the hash value of an object \var{o}. On |
| 1673 failure, return \code{-1}. This is the equivalent of the Python | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1674 expression \samp{hash(\var{o})}.\bifuncindex{hash} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1675 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1676 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1677 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1678 \begin{cfuncdesc}{int}{PyObject_IsTrue}{PyObject *o} |
| 7308 | 1679 Returns \code{1} if the object \var{o} is considered to be true, and |
| 1680 \code{0} otherwise. This is equivalent to the Python expression | |
| 1681 \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
|
1682 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
|
1683 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1684 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1685 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1686 \begin{cfuncdesc}{PyObject*}{PyObject_Type}{PyObject *o} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
1687 When \var{o} is non-\NULL, returns a type object corresponding to the |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
1688 object type of object \var{o}. On failure, raises |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
1689 \exception{SystemError} and returns \NULL. This is equivalent to the |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
1690 Python expression \code{type(\var{o})}. |
|
7309
d7266372dd37
Added index enties for the Python built-in functions, where appropriate.
Fred Drake <fdrake@acm.org>
parents:
7308
diff
changeset
|
1691 \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
|
1692 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1693 |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
1694 \begin{cfuncdesc}{int}{PyObject_TypeCheck}{PyObject *o, PyTypeObject *type} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
1695 Return true if the object \var{o} is of type \var{type} or a subtype |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
1696 of \var{type}. Both parameters must be non-\NULL. |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
1697 \versionadded{2.2} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
1698 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
1699 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1700 \begin{cfuncdesc}{int}{PyObject_Length}{PyObject *o} |
| 7308 | 1701 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
|
1702 both sequence and mapping protocols, the sequence length is |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1703 returned. On error, \code{-1} is returned. This is the equivalent |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1704 to the Python expression \samp{len(\var{o})}.\bifuncindex{len} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1705 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1706 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1707 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1708 \begin{cfuncdesc}{PyObject*}{PyObject_GetItem}{PyObject *o, PyObject *key} |
| 7308 | 1709 Return element of \var{o} corresponding to the object \var{key} or |
| 1710 \NULL{} on failure. This is the equivalent of the Python expression | |
| 1711 \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
|
1712 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1713 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1714 |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1715 \begin{cfuncdesc}{int}{PyObject_SetItem}{PyObject *o, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1716 PyObject *key, PyObject *v} |
| 7308 | 1717 Map the object \var{key} to the value \var{v}. |
| 1718 Returns \code{-1} on failure. This is the equivalent | |
| 1719 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
|
1720 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1721 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1722 |
|
9931
00fc18ac6aeb
Header for PyObject_DelItem() mentioned non-existing 3rd argument.
Guido van Rossum <guido@python.org>
parents:
9476
diff
changeset
|
1723 \begin{cfuncdesc}{int}{PyObject_DelItem}{PyObject *o, PyObject *key} |
| 7308 | 1724 Delete the mapping for \var{key} from \var{o}. Returns \code{-1} on |
| 1725 failure. This is the equivalent of the Python statement \samp{del | |
| 1726 \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
|
1727 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1728 |
|
13592
9ca50e2433eb
Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents:
13404
diff
changeset
|
1729 \begin{cfuncdesc}{int}{PyObject_AsFileDescriptor}{PyObject *o} |
|
9ca50e2433eb
Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents:
13404
diff
changeset
|
1730 Derives a file-descriptor from a Python object. If the object |
|
9ca50e2433eb
Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents:
13404
diff
changeset
|
1731 is an integer or long integer, its value is returned. If not, the |
|
9ca50e2433eb
Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents:
13404
diff
changeset
|
1732 object's \method{fileno()} method is called if it exists; the method |
|
9ca50e2433eb
Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents:
13404
diff
changeset
|
1733 must return an integer or long integer, which is returned as the file |
|
9ca50e2433eb
Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents:
13404
diff
changeset
|
1734 descriptor value. Returns \code{-1} on failure. |
|
9ca50e2433eb
Document PyObject_AsFileDescriptor
Andrew M. Kuchling <amk@amk.ca>
parents:
13404
diff
changeset
|
1735 \end{cfuncdesc} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1736 |
|
19705
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1737 \begin{cfuncdesc}{PyObject*}{PyObject_Dir}{PyObject *o} |
|
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1738 This is equivalent to the Python expression \samp{dir(\var{o})}, |
|
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1739 returning a (possibly empty) list of strings appropriate for the |
|
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1740 object argument, or \NULL{} in case of error. |
|
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1741 If the argument is \NULL{}, this is like the Python \samp{dir()}, |
|
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1742 returning the names of the current locals; in this case, if no |
|
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1743 execution frame is active then \NULL{} is returned but |
|
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1744 \cfunction{PyErr_Occurred()} will return false. |
|
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1745 \end{cfuncdesc} |
|
b7f6fbc087a7
At Guido's suggestion, here's a new C API function, PyObject_Dir(), like
Tim Peters <tim.peters@gmail.com>
parents:
19607
diff
changeset
|
1746 |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1747 |
| 10163 | 1748 \section{Number Protocol \label{number}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1749 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1750 \begin{cfuncdesc}{int}{PyNumber_Check}{PyObject *o} |
| 7308 | 1751 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
|
1752 false otherwise. |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1753 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
|
1754 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1755 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1756 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1757 \begin{cfuncdesc}{PyObject*}{PyNumber_Add}{PyObject *o1, PyObject *o2} |
| 7308 | 1758 Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on |
| 1759 failure. This is the equivalent of the Python expression | |
| 1760 \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
|
1761 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1762 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1763 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1764 \begin{cfuncdesc}{PyObject*}{PyNumber_Subtract}{PyObject *o1, PyObject *o2} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1765 Returns the result of subtracting \var{o2} from \var{o1}, or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1766 \NULL{} on failure. This is the equivalent of the Python expression |
| 7308 | 1767 \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
|
1768 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1769 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1770 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1771 \begin{cfuncdesc}{PyObject*}{PyNumber_Multiply}{PyObject *o1, PyObject *o2} |
| 7308 | 1772 Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on |
| 1773 failure. This is the equivalent of the Python expression | |
| 1774 \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
|
1775 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1776 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1777 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1778 \begin{cfuncdesc}{PyObject*}{PyNumber_Divide}{PyObject *o1, PyObject *o2} |
| 7308 | 1779 Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on |
| 1780 failure. | |
| 1781 This is the equivalent of the Python expression \samp{\var{o1} / | |
| 1782 \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
|
1783 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1784 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1785 |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1786 \begin{cfuncdesc}{PyObject*}{PyNumber_FloorDivide}{PyObject *o1, PyObject *o2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1787 Return the floor of \var{o1} divided by \var{o2}, or \NULL{} on |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1788 failure. This is equivalent to the ``classic'' division of integers. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1789 \versionadded{2.2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1790 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1791 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1792 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1793 \begin{cfuncdesc}{PyObject*}{PyNumber_TrueDivide}{PyObject *o1, PyObject *o2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1794 Return a reasonable approximation for the mathematical value of |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1795 \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1796 is ``approximate'' because binary floating point numbers are |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1797 approximate; it is not possible to represent all real numbers in base |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1798 two. This function can return a floating point value when passed two |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1799 integers. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1800 \versionadded{2.2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1801 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1802 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1803 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1804 \begin{cfuncdesc}{PyObject*}{PyNumber_Remainder}{PyObject *o1, PyObject *o2} |
| 7308 | 1805 Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on |
| 1806 failure. This is the equivalent of the Python expression | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1807 \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
|
1808 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1809 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1810 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1811 \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
|
1812 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
|
1813 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
|
1814 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
|
1815 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1816 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1817 |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1818 \begin{cfuncdesc}{PyObject*}{PyNumber_Power}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1819 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
|
1820 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
|
1821 \NULL{} on failure. This is the equivalent of the Python expression |
| 7308 | 1822 \samp{pow(\var{o1}, \var{o2}, \var{o3})}, where \var{o3} is optional. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1823 If \var{o3} is to be ignored, pass \cdata{Py_None} in its place |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1824 (passing \NULL{} for \var{o3} would cause an illegal memory access). |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1825 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1826 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1827 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1828 \begin{cfuncdesc}{PyObject*}{PyNumber_Negative}{PyObject *o} |
| 7308 | 1829 Returns the negation of \var{o} on success, or \NULL{} on failure. |
| 1830 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
|
1831 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1832 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1833 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1834 \begin{cfuncdesc}{PyObject*}{PyNumber_Positive}{PyObject *o} |
| 7308 | 1835 Returns \var{o} on success, or \NULL{} on failure. |
| 1836 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
|
1837 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1838 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1839 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1840 \begin{cfuncdesc}{PyObject*}{PyNumber_Absolute}{PyObject *o} |
| 7308 | 1841 Returns the absolute value of \var{o}, or \NULL{} on failure. This is |
| 1842 the equivalent of the Python expression \samp{abs(\var{o})}. | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
1843 \bifuncindex{abs} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1844 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1845 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1846 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1847 \begin{cfuncdesc}{PyObject*}{PyNumber_Invert}{PyObject *o} |
| 7308 | 1848 Returns the bitwise negation of \var{o} on success, or \NULL{} on |
| 1849 failure. This is the equivalent of the Python expression | |
| 1850 \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
|
1851 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1852 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1853 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1854 \begin{cfuncdesc}{PyObject*}{PyNumber_Lshift}{PyObject *o1, PyObject *o2} |
| 7308 | 1855 Returns the result of left shifting \var{o1} by \var{o2} on success, |
| 1856 or \NULL{} on failure. This is the equivalent of the Python | |
|
17480
04daee3ab627
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17336
diff
changeset
|
1857 expression \samp{\var{o1} <\code{<} \var{o2}}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1858 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1859 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1860 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1861 \begin{cfuncdesc}{PyObject*}{PyNumber_Rshift}{PyObject *o1, PyObject *o2} |
| 7308 | 1862 Returns the result of right shifting \var{o1} by \var{o2} on success, |
| 1863 or \NULL{} on failure. This is the equivalent of the Python | |
|
17480
04daee3ab627
Work around the conversion of ">>" and "<<" to guillemets. Reported by Ping.
Fred Drake <fdrake@acm.org>
parents:
17336
diff
changeset
|
1864 expression \samp{\var{o1} >\code{>} \var{o2}}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1865 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1866 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1867 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1868 \begin{cfuncdesc}{PyObject*}{PyNumber_And}{PyObject *o1, PyObject *o2} |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1869 Returns the ``bitwise and'' of \var{o2} and \var{o2} on success and |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1870 \NULL{} on failure. This is the equivalent of the Python expression |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
1871 \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
|
1872 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1873 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1874 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1875 \begin{cfuncdesc}{PyObject*}{PyNumber_Xor}{PyObject *o1, PyObject *o2} |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1876 Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on success, |
| 7308 | 1877 or \NULL{} on failure. This is the equivalent of the Python |
| 18576 | 1878 expression \samp{\var{o1} \textasciicircum{} \var{o2}}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1879 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1880 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
1881 \begin{cfuncdesc}{PyObject*}{PyNumber_Or}{PyObject *o1, PyObject *o2} |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1882 Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1883 \NULL{} on failure. This is the equivalent of the Python expression |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1884 \samp{\var{o1} | \var{o2}}. |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1885 \end{cfuncdesc} |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1886 |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1887 |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1888 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAdd}{PyObject *o1, PyObject *o2} |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1889 Returns the result of adding \var{o1} and \var{o2}, or \NULL{} on |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1890 failure. The operation is done \emph{in-place} when \var{o1} supports |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1891 it. This is the equivalent of the Python statement \samp{\var{o1} += |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1892 \var{o2}}. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1893 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1894 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1895 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1896 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceSubtract}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1897 PyObject *o2} |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1898 Returns the result of subtracting \var{o2} from \var{o1}, or |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1899 \NULL{} on failure. The operation is done \emph{in-place} when |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1900 \var{o1} supports it. This is the equivalent of the Python statement |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1901 \samp{\var{o1} -= \var{o2}}. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1902 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1903 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1904 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1905 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceMultiply}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1906 PyObject *o2} |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1907 Returns the result of multiplying \var{o1} and \var{o2}, or \NULL{} on |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1908 failure. The operation is done \emph{in-place} when \var{o1} supports it. |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1909 This is the equivalent of the Python statement \samp{\var{o1} *= \var{o2}}. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1910 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1911 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1912 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1913 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceDivide}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1914 PyObject *o2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1915 Returns the result of dividing \var{o1} by \var{o2}, or \NULL{} on |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1916 failure. The operation is done \emph{in-place} when \var{o1} supports |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1917 it. This is the equivalent of the Python statement \samp{\var{o1} /= |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1918 \var{o2}}. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1919 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1920 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1921 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1922 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceFloorDivide}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1923 PyObject *o2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1924 Returns the mathematical of dividing \var{o1} by \var{o2}, or \NULL{} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1925 on failure. The operation is done \emph{in-place} when \var{o1} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1926 supports it. This is the equivalent of the Python statement |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1927 \samp{\var{o1} //= \var{o2}}. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1928 \versionadded{2.2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1929 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1930 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1931 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1932 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceTrueDivide}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1933 PyObject *o2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1934 Return a reasonable approximation for the mathematical value of |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1935 \var{o1} divided by \var{o2}, or \NULL{} on failure. The return value |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1936 is ``approximate'' because binary floating point numbers are |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1937 approximate; it is not possible to represent all real numbers in base |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1938 two. This function can return a floating point value when passed two |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1939 integers. The operation is done \emph{in-place} when \var{o1} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1940 supports it. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1941 \versionadded{2.2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1942 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1943 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1944 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1945 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRemainder}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1946 PyObject *o2} |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1947 Returns the remainder of dividing \var{o1} by \var{o2}, or \NULL{} on |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1948 failure. The operation is done \emph{in-place} when \var{o1} supports it. |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1949 This is the equivalent of the Python statement \samp{\var{o1} \%= \var{o2}}. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1950 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1951 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1952 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1953 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlacePower}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1954 PyObject *o2, PyObject *o3} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1955 See the built-in function \function{pow()}.\bifuncindex{pow} Returns |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1956 \NULL{} on failure. The operation is done \emph{in-place} when |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1957 \var{o1} supports it. This is the equivalent of the Python statement |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1958 \samp{\var{o1} **= \var{o2}} when o3 is \cdata{Py_None}, or an |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1959 in-place variant of \samp{pow(\var{o1}, \var{o2}, \var{o3})} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1960 otherwise. If \var{o3} is to be ignored, pass \cdata{Py_None} in its |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1961 place (passing \NULL{} for \var{o3} would cause an illegal memory |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1962 access). |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1963 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1964 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1965 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceLshift}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1966 PyObject *o2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1967 Returns the result of left shifting \var{o1} by \var{o2} on success, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1968 or \NULL{} on failure. The operation is done \emph{in-place} when |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1969 \var{o1} supports it. This is the equivalent of the Python statement |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1970 \samp{\var{o1} <\code{<=} \var{o2}}. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1971 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1972 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1973 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1974 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceRshift}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1975 PyObject *o2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1976 Returns the result of right shifting \var{o1} by \var{o2} on success, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1977 or \NULL{} on failure. The operation is done \emph{in-place} when |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1978 \var{o1} supports it. This is the equivalent of the Python statement |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1979 \samp{\var{o1} >\code{>=} \var{o2}}. |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1980 \end{cfuncdesc} |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1981 |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1982 |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1983 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceAnd}{PyObject *o1, PyObject *o2} |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
1984 Returns the ``bitwise and'' of \var{o1} and \var{o2} on success |
|
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
1985 and \NULL{} on failure. The operation is done \emph{in-place} when |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1986 \var{o1} supports it. This is the equivalent of the Python statement |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
1987 \samp{\var{o1} \&= \var{o2}}. |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1988 \end{cfuncdesc} |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1989 |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1990 |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1991 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceXor}{PyObject *o1, PyObject *o2} |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1992 Returns the ``bitwise exclusive or'' of \var{o1} by \var{o2} on |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1993 success, or \NULL{} on failure. The operation is done \emph{in-place} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1994 when \var{o1} supports it. This is the equivalent of the Python |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1995 statement \samp{\var{o1} \textasciicircum= \var{o2}}. |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1996 \end{cfuncdesc} |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1997 |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
1998 \begin{cfuncdesc}{PyObject*}{PyNumber_InPlaceOr}{PyObject *o1, PyObject *o2} |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
1999 Returns the ``bitwise or'' of \var{o1} and \var{o2} on success, or |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
2000 \NULL{} on failure. The operation is done \emph{in-place} when |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
2001 \var{o1} supports it. This is the equivalent of the Python statement |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
2002 \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
|
2003 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2004 |
|
14769
aa18e5239b46
PyNumber_Coerce() returns an int, not a PyObject *.
Fred Drake <fdrake@acm.org>
parents:
14736
diff
changeset
|
2005 \begin{cfuncdesc}{int}{PyNumber_Coerce}{PyObject **p1, PyObject **p2} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2006 This function takes the addresses of two variables of type |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2007 \ctype{PyObject*}. If the objects pointed to by \code{*\var{p1}} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2008 \code{*\var{p2}} have the same type, increment their reference count |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2009 and return \code{0} (success). If the objects can be converted to a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2010 common numeric type, replace \code{*p1} and \code{*p2} by their |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2011 converted value (with 'new' reference counts), and return \code{0}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2012 If no conversion is possible, or if some other error occurs, return |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2013 \code{-1} (failure) and don't increment the reference counts. The |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2014 call \code{PyNumber_Coerce(\&o1, \&o2)} is equivalent to the Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2015 statement \samp{\var{o1}, \var{o2} = coerce(\var{o1}, \var{o2})}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2016 \bifuncindex{coerce} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2017 \end{cfuncdesc} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2018 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2019 \begin{cfuncdesc}{PyObject*}{PyNumber_Int}{PyObject *o} |
| 7308 | 2020 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
|
2021 \NULL{} on failure. This is the equivalent of the Python |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2022 expression \samp{int(\var{o})}.\bifuncindex{int} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2023 \end{cfuncdesc} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2024 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2025 \begin{cfuncdesc}{PyObject*}{PyNumber_Long}{PyObject *o} |
| 7308 | 2026 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
|
2027 or \NULL{} on failure. This is the equivalent of the Python |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2028 expression \samp{long(\var{o})}.\bifuncindex{long} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2029 \end{cfuncdesc} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2030 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2031 \begin{cfuncdesc}{PyObject*}{PyNumber_Float}{PyObject *o} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2032 Returns the \var{o} converted to a float object on success, or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2033 \NULL{} on failure. This is the equivalent of the Python expression |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2034 \samp{float(\var{o})}.\bifuncindex{float} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2035 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2036 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2037 |
| 10163 | 2038 \section{Sequence Protocol \label{sequence}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2039 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2040 \begin{cfuncdesc}{int}{PySequence_Check}{PyObject *o} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2041 Return \code{1} if the object provides sequence protocol, and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2042 \code{0} otherwise. This function always succeeds. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2043 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2044 |
|
17307
288d805af142
Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents:
17242
diff
changeset
|
2045 \begin{cfuncdesc}{int}{PySequence_Size}{PyObject *o} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2046 Returns the number of objects in sequence \var{o} on success, and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2047 \code{-1} on failure. For objects that do not provide sequence |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2048 protocol, this is equivalent to the Python expression |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2049 \samp{len(\var{o})}.\bifuncindex{len} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2050 \end{cfuncdesc} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2051 |
|
17307
288d805af142
Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents:
17242
diff
changeset
|
2052 \begin{cfuncdesc}{int}{PySequence_Length}{PyObject *o} |
|
288d805af142
Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents:
17242
diff
changeset
|
2053 Alternate name for \cfunction{PySequence_Size()}. |
|
288d805af142
Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents:
17242
diff
changeset
|
2054 \end{cfuncdesc} |
|
288d805af142
Document PySequence_Size(), and describe PySequence_Length() as simply an
Fred Drake <fdrake@acm.org>
parents:
17242
diff
changeset
|
2055 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2056 \begin{cfuncdesc}{PyObject*}{PySequence_Concat}{PyObject *o1, PyObject *o2} |
| 7308 | 2057 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
|
2058 failure. This is the equivalent of the Python |
| 7308 | 2059 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
|
2060 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2061 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2062 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2063 \begin{cfuncdesc}{PyObject*}{PySequence_Repeat}{PyObject *o, int count} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2064 Return the result of repeating sequence object |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2065 \var{o} \var{count} times, or \NULL{} on failure. This is the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2066 equivalent of the Python expression \samp{\var{o} * \var{count}}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2067 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2068 |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
2069 \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceConcat}{PyObject *o1, |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
2070 PyObject *o2} |
|
14528
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2071 Return the concatenation of \var{o1} and \var{o2} on success, and \NULL{} on |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2072 failure. The operation is done \emph{in-place} when \var{o1} supports it. |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2073 This is the equivalent of the Python expression \samp{\var{o1} += \var{o2}}. |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2074 \end{cfuncdesc} |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2075 |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2076 |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2077 \begin{cfuncdesc}{PyObject*}{PySequence_InPlaceRepeat}{PyObject *o, int count} |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2078 Return the result of repeating sequence object \var{o} \var{count} times, or |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2079 \NULL{} on failure. The operation is done \emph{in-place} when \var{o} |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2080 supports it. This is the equivalent of the Python expression \samp{\var{o} |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2081 *= \var{count}}. |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2082 \end{cfuncdesc} |
|
7366bb95f212
Thomas Wouters <thomas@xs4all.net>:
Fred Drake <fdrake@acm.org>
parents:
14526
diff
changeset
|
2083 |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2084 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2085 \begin{cfuncdesc}{PyObject*}{PySequence_GetItem}{PyObject *o, int i} |
| 7308 | 2086 Return the \var{i}th element of \var{o}, or \NULL{} on failure. This |
| 2087 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
|
2088 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2089 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2090 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2091 \begin{cfuncdesc}{PyObject*}{PySequence_GetSlice}{PyObject *o, int i1, int i2} |
| 7308 | 2092 Return the slice of sequence object \var{o} between \var{i1} and |
| 2093 \var{i2}, or \NULL{} on failure. This is the equivalent of the Python | |
| 2094 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
|
2095 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2096 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2097 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2098 \begin{cfuncdesc}{int}{PySequence_SetItem}{PyObject *o, int i, PyObject *v} |
| 7308 | 2099 Assign object \var{v} to the \var{i}th element of \var{o}. |
| 2100 Returns \code{-1} on failure. This is the equivalent of the Python | |
| 2101 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
|
2102 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2103 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2104 \begin{cfuncdesc}{int}{PySequence_DelItem}{PyObject *o, int i} |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
2105 Delete the \var{i}th element of object \var{o}. Returns |
| 7308 | 2106 \code{-1} on failure. This is the equivalent of the Python |
| 2107 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
|
2108 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2109 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2110 \begin{cfuncdesc}{int}{PySequence_SetSlice}{PyObject *o, int i1, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2111 int i2, PyObject *v} |
| 7308 | 2112 Assign the sequence object \var{v} to the slice in sequence |
| 2113 object \var{o} from \var{i1} to \var{i2}. This is the equivalent of | |
| 2114 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
|
2115 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2116 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2117 \begin{cfuncdesc}{int}{PySequence_DelSlice}{PyObject *o, int i1, int i2} |
| 7308 | 2118 Delete the slice in sequence object \var{o} from \var{i1} to \var{i2}. |
| 2119 Returns \code{-1} on failure. This is the equivalent of the Python | |
| 2120 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
|
2121 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2122 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2123 \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} |
| 7308 | 2124 Returns the \var{o} as a tuple on success, and \NULL{} on failure. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2125 This is equivalent to the Python expression \samp{tuple(\var{o})}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2126 \bifuncindex{tuple} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2127 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2128 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2129 \begin{cfuncdesc}{int}{PySequence_Count}{PyObject *o, PyObject *value} |
| 7308 | 2130 Return the number of occurrences of \var{value} in \var{o}, that is, |
| 2131 return the number of keys for which \code{\var{o}[\var{key}] == | |
| 2132 \var{value}}. On failure, return \code{-1}. This is equivalent to | |
| 2133 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
|
2134 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2135 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2136 \begin{cfuncdesc}{int}{PySequence_Contains}{PyObject *o, PyObject *value} |
| 7308 | 2137 Determine if \var{o} contains \var{value}. If an item in \var{o} is |
| 2138 equal to \var{value}, return \code{1}, otherwise return \code{0}. On | |
| 2139 error, return \code{-1}. This is equivalent to the Python expression | |
| 2140 \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
|
2141 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2142 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2143 \begin{cfuncdesc}{int}{PySequence_Index}{PyObject *o, PyObject *value} |
| 7308 | 2144 Return the first index \var{i} for which \code{\var{o}[\var{i}] == |
| 2145 \var{value}}. On error, return \code{-1}. This is equivalent to | |
| 2146 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
|
2147 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2148 |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2149 \begin{cfuncdesc}{PyObject*}{PySequence_List}{PyObject *o} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2150 Return a list object with the same contents as the arbitrary sequence |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2151 \var{o}. The returned list is guaranteed to be new. |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2152 \end{cfuncdesc} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2153 |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2154 \begin{cfuncdesc}{PyObject*}{PySequence_Tuple}{PyObject *o} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2155 Return a tuple object with the same contents as the arbitrary sequence |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2156 \var{o}. If \var{o} is a tuple, a new reference will be returned, |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2157 otherwise a tuple will be constructed with the appropriate contents. |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2158 \end{cfuncdesc} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
2159 |
|
7493
6857acbe2e74
Added \label{}s for logical addressing.
Fred Drake <fdrake@acm.org>
parents:
7467
diff
changeset
|
2160 |
|
14519
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2161 \begin{cfuncdesc}{PyObject*}{PySequence_Fast}{PyObject *o, const char *m} |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2162 Returns the sequence \var{o} as a tuple, unless it is already a |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2163 tuple or list, in which case \var{o} is returned. Use |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2164 \cfunction{PySequence_Fast_GET_ITEM()} to access the members of the |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2165 result. Returns \NULL{} on failure. If the object is not a sequence, |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2166 raises \exception{TypeError} with \var{m} as the message text. |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2167 \end{cfuncdesc} |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2168 |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2169 \begin{cfuncdesc}{PyObject*}{PySequence_Fast_GET_ITEM}{PyObject *o, int i} |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2170 Return the \var{i}th element of \var{o}, assuming that \var{o} was |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2171 returned by \cfunction{PySequence_Fast()}, and that \var{i} is within |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2172 bounds. The caller is expected to get the length of the sequence by |
|
18000
ec9343ad1e60
Users of PySequence_GET_FAST() should get the length of the sequence using
Fred Drake <fdrake@acm.org>
parents:
17981
diff
changeset
|
2173 calling \cfunction{PySequence_Size()} on \var{o}, since lists and tuples |
|
14519
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2174 are guaranteed to always return their true length. |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2175 \end{cfuncdesc} |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2176 |
|
7435331b48ee
Added documentation for PySequence_Fast() and PySequence_Fast_GET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
14347
diff
changeset
|
2177 |
| 10163 | 2178 \section{Mapping Protocol \label{mapping}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2179 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2180 \begin{cfuncdesc}{int}{PyMapping_Check}{PyObject *o} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2181 Return \code{1} if the object provides mapping protocol, and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2182 \code{0} otherwise. This function always succeeds. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2183 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2184 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2185 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2186 \begin{cfuncdesc}{int}{PyMapping_Length}{PyObject *o} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2187 Returns the number of keys in object \var{o} on success, and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2188 \code{-1} on failure. For objects that do not provide mapping |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2189 protocol, this is equivalent to the Python expression |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2190 \samp{len(\var{o})}.\bifuncindex{len} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2191 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2192 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2193 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2194 \begin{cfuncdesc}{int}{PyMapping_DelItemString}{PyObject *o, char *key} |
| 7308 | 2195 Remove the mapping for object \var{key} from the object \var{o}. |
| 2196 Return \code{-1} on failure. This is equivalent to | |
| 2197 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
|
2198 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2199 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2200 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2201 \begin{cfuncdesc}{int}{PyMapping_DelItem}{PyObject *o, PyObject *key} |
| 7308 | 2202 Remove the mapping for object \var{key} from the object \var{o}. |
| 2203 Return \code{-1} on failure. This is equivalent to | |
| 2204 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
|
2205 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2206 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2207 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2208 \begin{cfuncdesc}{int}{PyMapping_HasKeyString}{PyObject *o, char *key} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2209 On success, return \code{1} if the mapping object has the key |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2210 \var{key} and \code{0} otherwise. This is equivalent to the Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2211 expression \samp{\var{o}.has_key(\var{key})}. |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2212 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
|
2213 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2214 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2215 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2216 \begin{cfuncdesc}{int}{PyMapping_HasKey}{PyObject *o, PyObject *key} |
| 7308 | 2217 Return \code{1} if the mapping object has the key \var{key} and |
| 2218 \code{0} otherwise. This is equivalent to the Python expression | |
| 2219 \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
|
2220 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
|
2221 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2222 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2223 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2224 \begin{cfuncdesc}{PyObject*}{PyMapping_Keys}{PyObject *o} |
| 7308 | 2225 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
|
2226 failure, return \NULL{}. This is equivalent to the Python |
| 7308 | 2227 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
|
2228 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2229 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2230 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2231 \begin{cfuncdesc}{PyObject*}{PyMapping_Values}{PyObject *o} |
| 7308 | 2232 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
|
2233 failure, return \NULL{}. This is equivalent to the Python |
| 7308 | 2234 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
|
2235 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2236 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2237 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2238 \begin{cfuncdesc}{PyObject*}{PyMapping_Items}{PyObject *o} |
| 7308 | 2239 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
|
2240 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
|
2241 failure, return \NULL{}. This is equivalent to the Python |
| 7308 | 2242 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
|
2243 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2244 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2245 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2246 \begin{cfuncdesc}{PyObject*}{PyMapping_GetItemString}{PyObject *o, char *key} |
| 7308 | 2247 Return element of \var{o} corresponding to the object \var{key} or |
| 2248 \NULL{} on failure. This is the equivalent of the Python expression | |
| 2249 \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
|
2250 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2251 |
|
17695
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2252 \begin{cfuncdesc}{int}{PyMapping_SetItemString}{PyObject *o, char *key, |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2253 PyObject *v} |
| 7308 | 2254 Map the object \var{key} to the value \var{v} in object \var{o}. |
| 2255 Returns \code{-1} on failure. This is the equivalent of the Python | |
| 2256 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
|
2257 \end{cfuncdesc} |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2258 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2259 |
|
17695
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2260 \section{Iterator Protocol \label{iterator}} |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2261 |
|
17696
ffc2923bad1a
Hmm... better add a version annotation for the Iterator Protocol section.
Fred Drake <fdrake@acm.org>
parents:
17695
diff
changeset
|
2262 \versionadded{2.2} |
|
ffc2923bad1a
Hmm... better add a version annotation for the Iterator Protocol section.
Fred Drake <fdrake@acm.org>
parents:
17695
diff
changeset
|
2263 |
|
17695
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2264 There are only a couple of functions specifically for working with |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2265 iterators. |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2266 |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2267 \begin{cfuncdesc}{int}{PyIter_Check}{PyObject *o} |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2268 Return true if the object \var{o} supports the iterator protocol. |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2269 \end{cfuncdesc} |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2270 |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2271 \begin{cfuncdesc}{PyObject*}{PyIter_Next}{PyObject *o} |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2272 Return the next value from the iteration \var{o}. If the object is |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2273 an iterator, this retrieves the next value from the iteration, and |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2274 returns \NULL{} with no exception set if there are no remaining |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2275 items. If the object is not an iterator, \exception{TypeError} is |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2276 raised, or if there is an error in retrieving the item, returns |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2277 \NULL{} and passes along the exception. |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2278 \end{cfuncdesc} |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2279 |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2280 To write a loop which iterates over an iterator, the C code should |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2281 look something like this: |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2282 |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2283 \begin{verbatim} |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2284 PyObject *iterator = ...; |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2285 PyObject *item; |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2286 |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2287 while (item = PyIter_Next(iter)) { |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2288 /* do something with item */ |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2289 } |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2290 if (PyErr_Occurred()) { |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2291 /* propogate error */ |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2292 } |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2293 else { |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2294 /* continue doing useful work */ |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2295 } |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2296 \end{verbatim} |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2297 |
|
1e902fc73645
Added documentation for PyIter_Check() and PyIter_Next().
Fred Drake <fdrake@acm.org>
parents:
17618
diff
changeset
|
2298 |
| 10163 | 2299 \chapter{Concrete Objects Layer \label{concrete}} |
|
5536
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2300 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
2301 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
|
2302 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
|
2303 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
|
2304 that it has the right type, you must perform a type check first; |
|
16053
aca05d75d232
Fixed a bunch of typos caught by Gilles Civario.
Fred Drake <fdrake@acm.org>
parents:
15953
diff
changeset
|
2305 for example, to check that an object is a dictionary, use |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2306 \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
|
2307 ``family tree'' of Python object types. |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2308 |
|
15300
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2309 \strong{Warning:} |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2310 While the functions described in this chapter carefully check the type |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2311 of the objects which are passed in, many of them do not check for |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2312 \NULL{} being passed instead of a valid object. Allowing \NULL{} to |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2313 be passed in can cause memory access violations and immediate |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2314 termination of the interpreter. |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2315 |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2316 |
| 10163 | 2317 \section{Fundamental Objects \label{fundamental}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2318 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2319 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
|
2320 \code{None}. |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2321 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2322 |
| 10163 | 2323 \subsection{Type Objects \label{typeObjects}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2324 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2325 \obindex{type} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2326 \begin{ctypedesc}{PyTypeObject} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2327 The C structure of the objects used to describe built-in types. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2328 \end{ctypedesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2329 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2330 \begin{cvardesc}{PyObject*}{PyType_Type} |
| 10163 | 2331 This is the type object for type objects; it is the same object as |
| 2332 \code{types.TypeType} in the Python layer. | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2333 \withsubitem{(in module types)}{\ttindex{TypeType}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2334 \end{cvardesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2335 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2336 \begin{cfuncdesc}{int}{PyType_Check}{PyObject *o} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2337 Returns true is the object \var{o} is a type object. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2338 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2339 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2340 \begin{cfuncdesc}{int}{PyType_HasFeature}{PyObject *o, int feature} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2341 Returns true if the type object \var{o} sets the feature |
|
16439
d557ff0a2f6c
Remove an now-false statement about there being only one type flag
Fred Drake <fdrake@acm.org>
parents:
16318
diff
changeset
|
2342 \var{feature}. Type features are denoted by single bit flags. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2343 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2344 |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2345 \begin{cfuncdesc}{int}{PyType_IsSubtype}{PyTypeObject *a, PyTypeObject *b} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2346 Returns true if \var{a} is a subtype of \var{b}. |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
2347 \versionadded{2.2} |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2348 \end{cfuncdesc} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2349 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2350 \begin{cfuncdesc}{PyObject*}{PyType_GenericAlloc}{PyTypeObject *type, |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2351 int nitems} |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
2352 \versionadded{2.2} |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2353 \end{cfuncdesc} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2354 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2355 \begin{cfuncdesc}{PyObject*}{PyType_GenericNew}{PyTypeObject *type, |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2356 PyObject *args, PyObject *kwds} |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
2357 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
2358 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
2359 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
2360 \begin{cfuncdesc}{int}{PyType_Ready}{PyTypeObject *type} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
2361 \versionadded{2.2} |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2362 \end{cfuncdesc} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
2363 |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2364 |
| 10163 | 2365 \subsection{The None Object \label{noneObject}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2366 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2367 \obindex{None@\texttt{None}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2368 Note that the \ctype{PyTypeObject} for \code{None} is not directly |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2369 exposed in the Python/C API. Since \code{None} is a singleton, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2370 testing for object identity (using \samp{==} in C) is sufficient. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2371 There is no \cfunction{PyNone_Check()} function for the same reason. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2372 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2373 \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
|
2374 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
|
2375 no methods. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2376 \end{cvardesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2377 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2378 |
|
18481
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2379 \section{Numeric Objects \label{numericObjects}} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2380 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2381 \obindex{numeric} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2382 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2383 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2384 \subsection{Plain Integer Objects \label{intObjects}} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2385 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2386 \obindex{integer} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2387 \begin{ctypedesc}{PyIntObject} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2388 This subtype of \ctype{PyObject} represents a Python integer object. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2389 \end{ctypedesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2390 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2391 \begin{cvardesc}{PyTypeObject}{PyInt_Type} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2392 This instance of \ctype{PyTypeObject} represents the Python plain |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2393 integer type. This is the same object as \code{types.IntType}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2394 \withsubitem{(in modules types)}{\ttindex{IntType}} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2395 \end{cvardesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2396 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2397 \begin{cfuncdesc}{int}{PyInt_Check}{PyObject* o} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2398 Returns true if \var{o} is of type \cdata{PyInt_Type} or a subtype of |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2399 \cdata{PyInt_Type}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2400 \versionchanged[Allowed subtypes to be accepted]{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2401 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2402 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2403 \begin{cfuncdesc}{int}{PyInt_CheckExact}{PyObject* o} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2404 Returns true if \var{o} is of type \cdata{PyInt_Type}, but not a |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2405 subtype of \cdata{PyInt_Type}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2406 \versionadded{2.2} |
|
18481
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2407 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2408 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2409 \begin{cfuncdesc}{PyObject*}{PyInt_FromLong}{long ival} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2410 Creates a new integer object with a value of \var{ival}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2411 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2412 The current implementation keeps an array of integer objects for all |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2413 integers between \code{-1} and \code{100}, when you create an int in |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2414 that range you actually just get back a reference to the existing |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2415 object. So it should be possible to change the value of \code{1}. I |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2416 suspect the behaviour of Python in this case is undefined. :-) |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2417 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2418 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2419 \begin{cfuncdesc}{long}{PyInt_AsLong}{PyObject *io} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2420 Will first attempt to cast the object to a \ctype{PyIntObject}, if |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2421 it is not already one, and then return its value. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2422 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2423 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2424 \begin{cfuncdesc}{long}{PyInt_AS_LONG}{PyObject *io} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2425 Returns the value of the object \var{io}. No error checking is |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2426 performed. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2427 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2428 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2429 \begin{cfuncdesc}{long}{PyInt_GetMax}{} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2430 Returns the system's idea of the largest integer it can handle |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2431 (\constant{LONG_MAX}\ttindex{LONG_MAX}, as defined in the system |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2432 header files). |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2433 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2434 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2435 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2436 \subsection{Long Integer Objects \label{longObjects}} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2437 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2438 \obindex{long integer} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2439 \begin{ctypedesc}{PyLongObject} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2440 This subtype of \ctype{PyObject} represents a Python long integer |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2441 object. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2442 \end{ctypedesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2443 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2444 \begin{cvardesc}{PyTypeObject}{PyLong_Type} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2445 This instance of \ctype{PyTypeObject} represents the Python long |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2446 integer type. This is the same object as \code{types.LongType}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2447 \withsubitem{(in modules types)}{\ttindex{LongType}} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2448 \end{cvardesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2449 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2450 \begin{cfuncdesc}{int}{PyLong_Check}{PyObject *p} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2451 Returns true if its argument is a \ctype{PyLongObject} or a subtype of |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2452 \ctype{PyLongObject}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2453 \versionchanged[Allowed subtypes to be accepted]{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2454 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2455 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2456 \begin{cfuncdesc}{int}{PyLong_CheckExact}{PyObject *p} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2457 Returns true if its argument is a \ctype{PyLongObject}, but not a |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2458 subtype of \ctype{PyLongObject}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2459 \versionadded{2.2} |
|
18481
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2460 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2461 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2462 \begin{cfuncdesc}{PyObject*}{PyLong_FromLong}{long v} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2463 Returns a new \ctype{PyLongObject} object from \var{v}, or \NULL{} on |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2464 failure. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2465 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2466 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2467 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLong}{unsigned long v} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2468 Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2469 long}, or \NULL{} on failure. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2470 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2471 |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2472 \begin{cfuncdesc}{PyObject*}{PyLong_FromLongLong}{long long v} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2473 Returns a new \ctype{PyLongObject} object from a C \ctype{long long}, |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2474 or \NULL{} on failure. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2475 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2476 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2477 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnsignedLongLong}{unsigned long long v} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2478 Returns a new \ctype{PyLongObject} object from a C \ctype{unsigned |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2479 long long}, or \NULL{} on failure. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2480 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2481 |
|
18481
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2482 \begin{cfuncdesc}{PyObject*}{PyLong_FromDouble}{double v} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2483 Returns a new \ctype{PyLongObject} object from the integer part of |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2484 \var{v}, or \NULL{} on failure. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2485 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2486 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2487 \begin{cfuncdesc}{PyObject*}{PyLong_FromString}{char *str, char **pend, |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2488 int base} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2489 Return a new \ctype{PyLongObject} based on the string value in |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2490 \var{str}, which is interpreted according to the radix in \var{base}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2491 If \var{pend} is non-\NULL, \code{*\var{pend}} will point to the first |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2492 character in \var{str} which follows the representation of the |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2493 number. If \var{base} is \code{0}, the radix will be determined base |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2494 on the leading characters of \var{str}: if \var{str} starts with |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2495 \code{'0x'} or \code{'0X'}, radix 16 will be used; if \var{str} starts |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2496 with \code{'0'}, radix 8 will be used; otherwise radix 10 will be |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2497 used. If \var{base} is not \code{0}, it must be between \code{2} and |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2498 \code{36}, inclusive. Leading spaces are ignored. If there are no |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2499 digits, \exception{ValueError} will be raised. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2500 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2501 |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2502 \begin{cfuncdesc}{PyObject*}{PyLong_FromUnicode}{Py_UNICODE *u, |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2503 int length, int base} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2504 Convert a sequence of Unicode digits to a Python long integer value. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2505 The first parameter, \var{u}, points to the first character of the |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2506 Unicode string, \var{length} gives the number of characters, and |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2507 \var{base} is the radix for the conversion. The radix must be in the |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2508 range [2, 36]; if it is out of range, \exception{ValueError} will be |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2509 raised. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2510 \versionadded{1.6} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2511 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2512 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2513 \begin{cfuncdesc}{PyObject*}{PyLong_FromVoidPtr}{void *p} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2514 Create a Python integer or long integer from the pointer \var{p}. The |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2515 pointer value can be retrieved from the resulting value using |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2516 \cfunction{PyLong_AsVoidPtr()}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2517 \versionadded{1.5.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2518 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2519 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2520 \begin{cfuncdesc}{long}{PyLong_AsLong}{PyObject *pylong} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2521 Returns a C \ctype{long} representation of the contents of |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2522 \var{pylong}. If \var{pylong} is greater than |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2523 \constant{LONG_MAX}\ttindex{LONG_MAX}, an \exception{OverflowError} is |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2524 raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2525 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2526 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2527 \begin{cfuncdesc}{unsigned long}{PyLong_AsUnsignedLong}{PyObject *pylong} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2528 Returns a C \ctype{unsigned long} representation of the contents of |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2529 \var{pylong}. If \var{pylong} is greater than |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2530 \constant{ULONG_MAX}\ttindex{ULONG_MAX}, an \exception{OverflowError} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2531 is raised.\withsubitem{(built-in exception)}{\ttindex{OverflowError}} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2532 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2533 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2534 \begin{cfuncdesc}{long long}{PyLong_AsLongLong}{PyObject *pylong} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2535 Return a C \ctype{long long} from a Python long integer. If |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2536 \var{pylong} cannot be represented as a \ctype{long long}, an |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2537 \exception{OverflowError} will be raised. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2538 \versionadded{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2539 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2540 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2541 \begin{cfuncdesc}{unsigned long long}{PyLong_AsUnsignedLongLong}{PyObject |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2542 *pylong} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2543 Return a C \ctype{unsigned long long} from a Python long integer. If |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2544 \var{pylong} cannot be represented as an \ctype{unsigned long long}, |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2545 an \exception{OverflowError} will be raised if the value is positive, |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2546 or a \exception{TypeError} will be raised if the value is negative. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2547 \versionadded{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2548 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2549 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2550 \begin{cfuncdesc}{double}{PyLong_AsDouble}{PyObject *pylong} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2551 Returns a C \ctype{double} representation of the contents of |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2552 \var{pylong}. If \var{pylong} cannot be approximately represented as |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2553 a \ctype{double}, an \exception{OverflowError} exception is raised and |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2554 \code{-1.0} will be returned. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2555 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2556 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2557 \begin{cfuncdesc}{void*}{PyLong_AsVoidPtr}{PyObject *pylong} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2558 Convert a Python integer or long integer \var{pylong} to a C |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2559 \ctype{void} pointer. If \var{pylong} cannot be converted, an |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2560 \exception{OverflowError} will be raised. This is only assured to |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2561 produce a usable \ctype{void} pointer for values created with |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2562 \cfunction{PyLong_FromVoidPtr()}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2563 \versionadded{1.5.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2564 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2565 |
|
18481
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2566 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2567 \subsection{Floating Point Objects \label{floatObjects}} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2568 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2569 \obindex{floating point} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2570 \begin{ctypedesc}{PyFloatObject} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2571 This subtype of \ctype{PyObject} represents a Python floating point |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2572 object. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2573 \end{ctypedesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2574 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2575 \begin{cvardesc}{PyTypeObject}{PyFloat_Type} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2576 This instance of \ctype{PyTypeObject} represents the Python floating |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2577 point type. This is the same object as \code{types.FloatType}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2578 \withsubitem{(in modules types)}{\ttindex{FloatType}} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2579 \end{cvardesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2580 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2581 \begin{cfuncdesc}{int}{PyFloat_Check}{PyObject *p} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2582 Returns true if its argument is a \ctype{PyFloatObject} or a subtype |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2583 of \ctype{PyFloatObject}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2584 \versionchanged[Allowed subtypes to be accepted]{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2585 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2586 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2587 \begin{cfuncdesc}{int}{PyFloat_CheckExact}{PyObject *p} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2588 Returns true if its argument is a \ctype{PyFloatObject}, but not a |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2589 subtype of \ctype{PyFloatObject}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2590 \versionadded{2.2} |
|
18481
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2591 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2592 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2593 \begin{cfuncdesc}{PyObject*}{PyFloat_FromDouble}{double v} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2594 Creates a \ctype{PyFloatObject} object from \var{v}, or \NULL{} on |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2595 failure. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2596 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2597 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2598 \begin{cfuncdesc}{double}{PyFloat_AsDouble}{PyObject *pyfloat} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2599 Returns a C \ctype{double} representation of the contents of \var{pyfloat}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2600 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2601 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2602 \begin{cfuncdesc}{double}{PyFloat_AS_DOUBLE}{PyObject *pyfloat} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2603 Returns a C \ctype{double} representation of the contents of |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2604 \var{pyfloat}, but without error checking. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2605 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2606 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2607 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2608 \subsection{Complex Number Objects \label{complexObjects}} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2609 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2610 \obindex{complex number} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2611 Python's complex number objects are implemented as two distinct types |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2612 when viewed from the C API: one is the Python object exposed to |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2613 Python programs, and the other is a C structure which represents the |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2614 actual complex number value. The API provides functions for working |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2615 with both. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2616 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2617 \subsubsection{Complex Numbers as C Structures} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2618 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2619 Note that the functions which accept these structures as parameters |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2620 and return them as results do so \emph{by value} rather than |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2621 dereferencing them through pointers. This is consistent throughout |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2622 the API. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2623 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2624 \begin{ctypedesc}{Py_complex} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2625 The C structure which corresponds to the value portion of a Python |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2626 complex number object. Most of the functions for dealing with complex |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2627 number objects use structures of this type as input or output values, |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2628 as appropriate. It is defined as: |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2629 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2630 \begin{verbatim} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2631 typedef struct { |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2632 double real; |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2633 double imag; |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2634 } Py_complex; |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2635 \end{verbatim} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2636 \end{ctypedesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2637 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2638 \begin{cfuncdesc}{Py_complex}{_Py_c_sum}{Py_complex left, Py_complex right} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2639 Return the sum of two complex numbers, using the C |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2640 \ctype{Py_complex} representation. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2641 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2642 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2643 \begin{cfuncdesc}{Py_complex}{_Py_c_diff}{Py_complex left, Py_complex right} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2644 Return the difference between two complex numbers, using the C |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2645 \ctype{Py_complex} representation. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2646 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2647 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2648 \begin{cfuncdesc}{Py_complex}{_Py_c_neg}{Py_complex complex} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2649 Return the negation of the complex number \var{complex}, using the C |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2650 \ctype{Py_complex} representation. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2651 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2652 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2653 \begin{cfuncdesc}{Py_complex}{_Py_c_prod}{Py_complex left, Py_complex right} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2654 Return the product of two complex numbers, using the C |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2655 \ctype{Py_complex} representation. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2656 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2657 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2658 \begin{cfuncdesc}{Py_complex}{_Py_c_quot}{Py_complex dividend, |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2659 Py_complex divisor} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2660 Return the quotient of two complex numbers, using the C |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2661 \ctype{Py_complex} representation. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2662 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2663 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2664 \begin{cfuncdesc}{Py_complex}{_Py_c_pow}{Py_complex num, Py_complex exp} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2665 Return the exponentiation of \var{num} by \var{exp}, using the C |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2666 \ctype{Py_complex} representation. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2667 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2668 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2669 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2670 \subsubsection{Complex Numbers as Python Objects} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2671 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2672 \begin{ctypedesc}{PyComplexObject} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2673 This subtype of \ctype{PyObject} represents a Python complex number object. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2674 \end{ctypedesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2675 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2676 \begin{cvardesc}{PyTypeObject}{PyComplex_Type} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2677 This instance of \ctype{PyTypeObject} represents the Python complex |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2678 number type. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2679 \end{cvardesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2680 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2681 \begin{cfuncdesc}{int}{PyComplex_Check}{PyObject *p} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2682 Returns true if its argument is a \ctype{PyComplexObject} or a subtype |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2683 of \ctype{PyComplexObject}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2684 \versionchanged[Allowed subtypes to be accepted]{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2685 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2686 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2687 \begin{cfuncdesc}{int}{PyComplex_CheckExact}{PyObject *p} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2688 Returns true if its argument is a \ctype{PyComplexObject}, but not a |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2689 subtype of \ctype{PyComplexObject}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2690 \versionadded{2.2} |
|
18481
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2691 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2692 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2693 \begin{cfuncdesc}{PyObject*}{PyComplex_FromCComplex}{Py_complex v} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2694 Create a new Python complex number object from a C |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2695 \ctype{Py_complex} value. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2696 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2697 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2698 \begin{cfuncdesc}{PyObject*}{PyComplex_FromDoubles}{double real, double imag} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2699 Returns a new \ctype{PyComplexObject} object from \var{real} and \var{imag}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2700 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2701 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2702 \begin{cfuncdesc}{double}{PyComplex_RealAsDouble}{PyObject *op} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2703 Returns the real part of \var{op} as a C \ctype{double}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2704 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2705 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2706 \begin{cfuncdesc}{double}{PyComplex_ImagAsDouble}{PyObject *op} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2707 Returns the imaginary part of \var{op} as a C \ctype{double}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2708 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2709 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2710 \begin{cfuncdesc}{Py_complex}{PyComplex_AsCComplex}{PyObject *op} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2711 Returns the \ctype{Py_complex} value of the complex number \var{op}. |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2712 \end{cfuncdesc} |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2713 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2714 |
|
795aa4590211
Move the section on concrete numeric objects before the section on
Fred Drake <fdrake@acm.org>
parents:
18447
diff
changeset
|
2715 |
| 10163 | 2716 \section{Sequence Objects \label{sequenceObjects}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2717 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2718 \obindex{sequence} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2719 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
|
2720 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
|
2721 objects that are intrinsic to the Python language. |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2722 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2723 |
| 10163 | 2724 \subsection{String Objects \label{stringObjects}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2725 |
|
15300
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2726 These functions raise \exception{TypeError} when expecting a string |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2727 parameter and are called with a non-string parameter. |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2728 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2729 \obindex{string} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2730 \begin{ctypedesc}{PyStringObject} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
2731 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
|
2732 \end{ctypedesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2733 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2734 \begin{cvardesc}{PyTypeObject}{PyString_Type} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2735 This instance of \ctype{PyTypeObject} represents the Python string |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2736 type; it is the same object as \code{types.TypeType} in the Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2737 layer.\withsubitem{(in module types)}{\ttindex{StringType}}. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2738 \end{cvardesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2739 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2740 \begin{cfuncdesc}{int}{PyString_Check}{PyObject *o} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2741 Returns true if the object \var{o} is a string object or an instance |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2742 of a subtype of the string type. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2743 \versionchanged[Allowed subtypes to be accepted]{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2744 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2745 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2746 \begin{cfuncdesc}{int}{PyString_CheckExact}{PyObject *o} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2747 Returns true if the object \var{o} is a string object, but not an |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2748 instance of a subtype of the string type. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2749 \versionadded{2.2} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2750 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2751 |
| 7782 | 2752 \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
|
2753 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
|
2754 \NULL{} on failure. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2755 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2756 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2757 \begin{cfuncdesc}{PyObject*}{PyString_FromStringAndSize}{const char *v, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2758 int len} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2759 Returns a new string object with the value \var{v} and length |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2760 \var{len} on success, and \NULL{} on failure. If \var{v} is \NULL{}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2761 the contents of the string are uninitialized. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2762 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2763 |
|
19524
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2764 \begin{cfuncdesc}{PyObject*}{PyString_FromFormat}{const char *format, ...} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2765 Takes a C \code{printf}-style \var{format} string and a variable |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2766 number of arguments, calculates the size of the resulting Python |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2767 string and returns a string with the values formatted into it. The |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2768 variable arguments must be C types and must correspond exactly to the |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2769 format characters in the \var{format} string. The following format |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2770 characters are allowed: |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2771 \begin{tableiii}{l|l|l}{member}{Format Characters}{Type}{Comment} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2772 \lineiii{\%\%}{\emph{n/a}}{The literal \% character.} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2773 \lineiii{\%c}{int}{A single character, represented as an C int.} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2774 \lineiii{\%d}{int}{Exactly equivalent to \code{printf("\%d")}.} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2775 \lineiii{\%ld}{long}{Exactly equivalent to \code{printf("\%ld")}.} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2776 \lineiii{\%i}{int}{Exactly equivalent to \code{printf("\%i")}.} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2777 \lineiii{\%x}{int}{Exactly equivalent to \code{printf("\%x")}.} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2778 \lineiii{\%s}{char*}{A null-terminated C character array.} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2779 \lineiii{\%p}{void*}{The hex representation of a C pointer. |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2780 Mostly equivalent to \code{printf("\%p")} except that it is |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2781 guaranteed to start with the literal \code{0x} regardless of |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2782 what the platform's \code{printf} yields.} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2783 \end{tableiii} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2784 \end{cfuncdesc} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2785 |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2786 \begin{cfuncdesc}{PyObject*}{PyString_FromFormatV}{const char *format, |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2787 va_list vargs} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2788 Identical to \function{PyString_FromFormat()} except that it takes |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2789 exactly two arguments. |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2790 \end{cfuncdesc} |
|
ab194f1f053b
Documentation for PyString_FromFormat() and PyString_FromFormatV().
Barry Warsaw <barry@python.org>
parents:
19399
diff
changeset
|
2791 |
| 7782 | 2792 \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
|
2793 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
|
2794 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2795 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2796 \begin{cfuncdesc}{int}{PyString_GET_SIZE}{PyObject *string} |
|
15087
a13a2acbe214
Fix a couple of places where the descriptions of *_GET_SIZE() macros said
Fred Drake <fdrake@acm.org>
parents:
15038
diff
changeset
|
2797 Macro form of \cfunction{PyString_Size()} but without error |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2798 checking. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2799 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2800 |
| 7782 | 2801 \begin{cfuncdesc}{char*}{PyString_AsString}{PyObject *string} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2802 Returns a null-terminated representation of the contents of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2803 \var{string}. The pointer refers to the internal buffer of |
|
15300
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2804 \var{string}, not a copy. The data must not be modified in any way, |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2805 unless the string was just created using |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2806 \code{PyString_FromStringAndSize(NULL, \var{size})}. |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2807 It must not be deallocated. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2808 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2809 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2810 \begin{cfuncdesc}{char*}{PyString_AS_STRING}{PyObject *string} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2811 Macro form of \cfunction{PyString_AsString()} but without error |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2812 checking. |
| 7782 | 2813 \end{cfuncdesc} |
| 2814 | |
|
14696
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2815 \begin{cfuncdesc}{int}{PyString_AsStringAndSize}{PyObject *obj, |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2816 char **buffer, |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2817 int *length} |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2818 Returns a null-terminated representation of the contents of the object |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2819 \var{obj} through the output variables \var{buffer} and \var{length}. |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2820 |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2821 The function accepts both string and Unicode objects as input. For |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2822 Unicode objects it returns the default encoded version of the object. |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2823 If \var{length} is set to \NULL{}, the resulting buffer may not contain |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2824 null characters; if it does, the function returns -1 and a |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2825 TypeError is raised. |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2826 |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2827 The buffer refers to an internal string buffer of \var{obj}, not a |
|
15300
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2828 copy. The data must not be modified in any way, unless the string was |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2829 just created using \code{PyString_FromStringAndSize(NULL, |
|
0da4ccc7e8cf
Added exception to the rule that the buffer returned by PyString_AsString()
Fred Drake <fdrake@acm.org>
parents:
15236
diff
changeset
|
2830 \var{size})}. It must not be deallocated. |
|
14696
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2831 \end{cfuncdesc} |
|
85038a024b19
This patch adds a new Python C API called PyString_AsStringAndSize()
Marc-André Lemburg <mal@egenix.com>
parents:
14635
diff
changeset
|
2832 |
| 7782 | 2833 \begin{cfuncdesc}{void}{PyString_Concat}{PyObject **string, |
| 2834 PyObject *newpart} | |
|
10170
7cf97658cae7
Be explicit about the reference count of the original value of the
Fred Drake <fdrake@acm.org>
parents:
10163
diff
changeset
|
2835 Creates a new string object in \var{*string} containing the |
|
12200
42f21e47b486
Improve explanation of reference counts for PyString_Concat().
Fred Drake <fdrake@acm.org>
parents:
12126
diff
changeset
|
2836 contents of \var{newpart} appended to \var{string}; the caller will |
|
42f21e47b486
Improve explanation of reference counts for PyString_Concat().
Fred Drake <fdrake@acm.org>
parents:
12126
diff
changeset
|
2837 own the new reference. The reference to the old value of \var{string} |
|
42f21e47b486
Improve explanation of reference counts for PyString_Concat().
Fred Drake <fdrake@acm.org>
parents:
12126
diff
changeset
|
2838 will be stolen. If the new string |
|
10170
7cf97658cae7
Be explicit about the reference count of the original value of the
Fred Drake <fdrake@acm.org>
parents:
10163
diff
changeset
|
2839 cannot be created, the old reference to \var{string} will still be |
|
7cf97658cae7
Be explicit about the reference count of the original value of the
Fred Drake <fdrake@acm.org>
parents:
10163
diff
changeset
|
2840 discarded and the value of \var{*string} will be set to |
|
7cf97658cae7
Be explicit about the reference count of the original value of the
Fred Drake <fdrake@acm.org>
parents:
10163
diff
changeset
|
2841 \NULL{}; the appropriate exception will be set. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2842 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2843 |
| 7782 | 2844 \begin{cfuncdesc}{void}{PyString_ConcatAndDel}{PyObject **string, |
| 2845 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
|
2846 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
|
2847 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
|
2848 the reference count of \var{newpart}. |
| 7782 | 2849 \end{cfuncdesc} |
| 2850 | |
| 2851 \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
|
2852 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
|
2853 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
|
2854 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
|
2855 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2856 |
| 7782 | 2857 \begin{cfuncdesc}{PyObject*}{PyString_Format}{PyObject *format, |
| 2858 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
|
2859 Returns a new string object from \var{format} and \var{args}. Analogous |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
2860 to \code{\var{format} \%\ \var{args}}. The \var{args} argument must be |
|
8109
2e49bc89fafa
Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents:
8057
diff
changeset
|
2861 a tuple. |
| 7782 | 2862 \end{cfuncdesc} |
| 2863 | |
| 2864 \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
|
2865 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
|
2866 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
|
2867 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
|
2868 \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
|
2869 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
|
2870 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
|
2871 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
|
2872 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
|
2873 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
|
2874 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
|
2875 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2876 |
| 7782 | 2877 \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
|
2878 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
|
2879 \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
|
2880 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
|
2881 interned string object with the same value. |
| 7782 | 2882 \end{cfuncdesc} |
| 2883 | |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2884 \begin{cfuncdesc}{PyObject*}{PyString_Decode}{const char *s, |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2885 int size, |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2886 const char *encoding, |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2887 const char *errors} |
|
17835
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2888 Creates an object by decoding \var{size} bytes of the encoded |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2889 buffer \var{s} using the codec registered |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2890 for \var{encoding}. \var{encoding} and \var{errors} have the same meaning |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2891 as the parameters of the same name in the unicode() builtin |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2892 function. The codec to be used is looked up using the Python codec |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2893 registry. Returns \NULL{} in case an exception was raised by the |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2894 codec. |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2895 \end{cfuncdesc} |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2896 |
|
17835
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2897 \begin{cfuncdesc}{PyObject*}{PyString_AsDecodedObject}{PyObject *str, |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2898 const char *encoding, |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2899 const char *errors} |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2900 Decodes a string object by passing it to the codec registered |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2901 for \var{encoding} and returns the result as Python |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2902 object. \var{encoding} and \var{errors} have the same meaning as the |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2903 parameters of the same name in the string .encode() method. The codec |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2904 to be used is looked up using the Python codec registry. Returns |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2905 \NULL{} in case an exception was raised by the codec. |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2906 \end{cfuncdesc} |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2907 |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2908 \begin{cfuncdesc}{PyObject*}{PyString_Encode}{const char *s, |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2909 int size, |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2910 const char *encoding, |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2911 const char *errors} |
|
17835
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2912 Encodes the \ctype{char} buffer of the given size by passing it to |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2913 the codec registered for \var{encoding} and returns a Python object. |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2914 \var{encoding} and \var{errors} have the same |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2915 meaning as the parameters of the same name in the string .encode() |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2916 method. The codec to be used is looked up using the Python codec |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2917 registry. Returns \NULL{} in case an exception was raised by the |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2918 codec. |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2919 \end{cfuncdesc} |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2920 |
|
17835
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2921 \begin{cfuncdesc}{PyObject*}{PyString_AsEncodedObject}{PyObject *str, |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2922 const char *encoding, |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2923 const char *errors} |
|
17835
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2924 Encodes a string object using the codec registered |
|
9ea87c0a7c04
This patch changes the way the string .encode() method works slightly
Marc-André Lemburg <mal@egenix.com>
parents:
17696
diff
changeset
|
2925 for \var{encoding} and returns the result as Python |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2926 object. \var{encoding} and \var{errors} have the same meaning as the |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2927 parameters of the same name in the string .encode() method. The codec |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2928 to be used is looked up using the Python codec registry. Returns |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2929 \NULL{} in case an exception was raised by the codec. |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2930 \end{cfuncdesc} |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
2931 |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
2932 |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2933 \subsection{Unicode Objects \label{unicodeObjects}} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2934 \sectionauthor{Marc-Andre Lemburg}{mal@lemburg.com} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2935 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2936 %--- Unicode Type ------------------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2937 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2938 These are the basic Unicode object types used for the Unicode |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2939 implementation in Python: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2940 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2941 \begin{ctypedesc}{Py_UNICODE} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2942 This type represents a 16-bit unsigned storage type which is used by |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2943 Python internally as basis for holding Unicode ordinals. On platforms |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2944 where \ctype{wchar_t} is available and also has 16-bits, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2945 \ctype{Py_UNICODE} is a typedef alias for \ctype{wchar_t} to enhance |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2946 native platform compatibility. On all other platforms, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2947 \ctype{Py_UNICODE} is a typedef alias for \ctype{unsigned short}. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2948 \end{ctypedesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2949 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2950 \begin{ctypedesc}{PyUnicodeObject} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2951 This subtype of \ctype{PyObject} represents a Python Unicode object. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2952 \end{ctypedesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2953 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2954 \begin{cvardesc}{PyTypeObject}{PyUnicode_Type} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2955 This instance of \ctype{PyTypeObject} represents the Python Unicode type. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2956 \end{cvardesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2957 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2958 %--- These are really C macros... is there a macrodesc TeX macro ? |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2959 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2960 The following APIs are really C macros and can be used to do fast |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2961 checks and to access internal read-only data of Unicode objects: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2962 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2963 \begin{cfuncdesc}{int}{PyUnicode_Check}{PyObject *o} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2964 Returns true if the object \var{o} is a Unicode object or an instance |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2965 of a Unicode subtype. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2966 \versionchanged[Allowed subtypes to be accepted]{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2967 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2968 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2969 \begin{cfuncdesc}{int}{PyUnicode_CheckExact}{PyObject *o} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2970 Returns true if the object \var{o} is a Unicode object, but not an |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2971 instance of a subtype. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
2972 \versionadded{2.2} |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2973 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2974 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2975 \begin{cfuncdesc}{int}{PyUnicode_GET_SIZE}{PyObject *o} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2976 Returns the size of the object. o has to be a |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2977 PyUnicodeObject (not checked). |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2978 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2979 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2980 \begin{cfuncdesc}{int}{PyUnicode_GET_DATA_SIZE}{PyObject *o} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2981 Returns the size of the object's internal buffer in bytes. o has to be |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2982 a PyUnicodeObject (not checked). |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2983 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2984 |
|
12932
1fa7c119b7a5
Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support.
Fred Drake <fdrake@acm.org>
parents:
12930
diff
changeset
|
2985 \begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AS_UNICODE}{PyObject *o} |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2986 Returns a pointer to the internal Py_UNICODE buffer of the object. o |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2987 has to be a PyUnicodeObject (not checked). |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2988 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2989 |
|
12932
1fa7c119b7a5
Updates from Marc-Andre Lemburg <mal@leburg.com> for the Unicode support.
Fred Drake <fdrake@acm.org>
parents:
12930
diff
changeset
|
2990 \begin{cfuncdesc}{const char*}{PyUnicode_AS_DATA}{PyObject *o} |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2991 Returns a (const char *) pointer to the internal buffer of the object. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2992 o has to be a PyUnicodeObject (not checked). |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2993 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2994 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2995 % --- Unicode character properties --------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2996 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2997 Unicode provides many different character properties. The most often |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2998 needed ones are available through these macros which are mapped to C |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
2999 functions depending on the Python configuration. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3000 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3001 \begin{cfuncdesc}{int}{Py_UNICODE_ISSPACE}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3002 Returns 1/0 depending on whether \var{ch} is a whitespace character. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3003 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3004 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3005 \begin{cfuncdesc}{int}{Py_UNICODE_ISLOWER}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3006 Returns 1/0 depending on whether \var{ch} is a lowercase character. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3007 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3008 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3009 \begin{cfuncdesc}{int}{Py_UNICODE_ISUPPER}{Py_UNICODE ch} |
|
13321
ac24d82d8e33
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
13217
diff
changeset
|
3010 Returns 1/0 depending on whether \var{ch} is an uppercase character. |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3011 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3012 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3013 \begin{cfuncdesc}{int}{Py_UNICODE_ISTITLE}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3014 Returns 1/0 depending on whether \var{ch} is a titlecase character. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3015 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3016 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3017 \begin{cfuncdesc}{int}{Py_UNICODE_ISLINEBREAK}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3018 Returns 1/0 depending on whether \var{ch} is a linebreak character. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3019 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3020 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3021 \begin{cfuncdesc}{int}{Py_UNICODE_ISDECIMAL}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3022 Returns 1/0 depending on whether \var{ch} is a decimal character. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3023 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3024 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3025 \begin{cfuncdesc}{int}{Py_UNICODE_ISDIGIT}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3026 Returns 1/0 depending on whether \var{ch} is a digit character. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3027 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3028 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3029 \begin{cfuncdesc}{int}{Py_UNICODE_ISNUMERIC}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3030 Returns 1/0 depending on whether \var{ch} is a numeric character. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3031 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3032 |
|
13321
ac24d82d8e33
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
13217
diff
changeset
|
3033 \begin{cfuncdesc}{int}{Py_UNICODE_ISALPHA}{Py_UNICODE ch} |
|
ac24d82d8e33
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
13217
diff
changeset
|
3034 Returns 1/0 depending on whether \var{ch} is an alphabetic character. |
|
ac24d82d8e33
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
13217
diff
changeset
|
3035 \end{cfuncdesc} |
|
ac24d82d8e33
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
13217
diff
changeset
|
3036 |
|
ac24d82d8e33
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
13217
diff
changeset
|
3037 \begin{cfuncdesc}{int}{Py_UNICODE_ISALNUM}{Py_UNICODE ch} |
|
ac24d82d8e33
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
13217
diff
changeset
|
3038 Returns 1/0 depending on whether \var{ch} is an alphanumeric character. |
|
ac24d82d8e33
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
13217
diff
changeset
|
3039 \end{cfuncdesc} |
|
ac24d82d8e33
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
13217
diff
changeset
|
3040 |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3041 These APIs can be used for fast direct character conversions: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3042 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3043 \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOLOWER}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3044 Returns the character \var{ch} converted to lower case. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3045 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3046 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3047 \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOUPPER}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3048 Returns the character \var{ch} converted to upper case. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3049 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3050 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3051 \begin{cfuncdesc}{Py_UNICODE}{Py_UNICODE_TOTITLE}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3052 Returns the character \var{ch} converted to title case. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3053 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3054 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3055 \begin{cfuncdesc}{int}{Py_UNICODE_TODECIMAL}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3056 Returns the character \var{ch} converted to a decimal positive integer. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3057 Returns -1 in case this is not possible. Does not raise exceptions. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3058 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3059 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3060 \begin{cfuncdesc}{int}{Py_UNICODE_TODIGIT}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3061 Returns the character \var{ch} converted to a single digit integer. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3062 Returns -1 in case this is not possible. Does not raise exceptions. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3063 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3064 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3065 \begin{cfuncdesc}{double}{Py_UNICODE_TONUMERIC}{Py_UNICODE ch} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3066 Returns the character \var{ch} converted to a (positive) double. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3067 Returns -1.0 in case this is not possible. Does not raise exceptions. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3068 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3069 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3070 % --- Plain Py_UNICODE --------------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3071 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3072 To create Unicode objects and access their basic sequence properties, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3073 use these APIs: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3074 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3075 \begin{cfuncdesc}{PyObject*}{PyUnicode_FromUnicode}{const Py_UNICODE *u, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3076 int size} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3077 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3078 Create a Unicode Object from the Py_UNICODE buffer \var{u} of the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3079 given size. \var{u} may be \NULL{} which causes the contents to be |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3080 undefined. It is the user's responsibility to fill in the needed data. |
|
17618
b44ba7c01217
This patch originated from an idea by Martin v. Loewis who submitted a
Marc-André Lemburg <mal@egenix.com>
parents:
17504
diff
changeset
|
3081 The buffer is copied into the new object. If the buffer is not \NULL{}, |
|
b44ba7c01217
This patch originated from an idea by Martin v. Loewis who submitted a
Marc-André Lemburg <mal@egenix.com>
parents:
17504
diff
changeset
|
3082 the return value might be a shared object. Therefore, modification of |
|
b44ba7c01217
This patch originated from an idea by Martin v. Loewis who submitted a
Marc-André Lemburg <mal@egenix.com>
parents:
17504
diff
changeset
|
3083 the resulting Unicode Object is only allowed when \var{u} is \NULL{}. |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3084 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3085 |
| 12947 | 3086 \begin{cfuncdesc}{Py_UNICODE*}{PyUnicode_AsUnicode}{PyObject *unicode} |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3087 Return a read-only pointer to the Unicode object's internal |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3088 \ctype{Py_UNICODE} buffer. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3089 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3090 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3091 \begin{cfuncdesc}{int}{PyUnicode_GetSize}{PyObject *unicode} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3092 Return the length of the Unicode object. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3093 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3094 |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3095 \begin{cfuncdesc}{PyObject*}{PyUnicode_FromEncodedObject}{PyObject *obj, |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3096 const char *encoding, |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3097 const char *errors} |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3098 |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3099 Coerce an encoded object obj to an Unicode object and return a |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3100 reference with incremented refcount. |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3101 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3102 Coercion is done in the following way: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3103 \begin{enumerate} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3104 \item Unicode objects are passed back as-is with incremented |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3105 refcount. Note: these cannot be decoded; passing a non-NULL |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3106 value for encoding will result in a TypeError. |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3107 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3108 \item String and other char buffer compatible objects are decoded |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3109 according to the given encoding and using the error handling |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3110 defined by errors. Both can be NULL to have the interface use |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3111 the default values (see the next section for details). |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3112 |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3113 \item All other objects cause an exception. |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3114 \end{enumerate} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3115 The API returns NULL in case of an error. The caller is responsible |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3116 for decref'ing the returned objects. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3117 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3118 |
|
13404
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3119 \begin{cfuncdesc}{PyObject*}{PyUnicode_FromObject}{PyObject *obj} |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3120 |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3121 Shortcut for PyUnicode_FromEncodedObject(obj, NULL, ``strict'') |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3122 which is used throughout the interpreter whenever coercion to |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3123 Unicode is needed. |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3124 \end{cfuncdesc} |
|
4cf21852fd52
Added docs for the new Unicode and string APIs.
Marc-André Lemburg <mal@egenix.com>
parents:
13321
diff
changeset
|
3125 |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3126 % --- wchar_t support for platforms which support it --------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3127 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3128 If the platform supports \ctype{wchar_t} and provides a header file |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3129 wchar.h, Python can interface directly to this type using the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3130 following functions. Support is optimized if Python's own |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3131 \ctype{Py_UNICODE} type is identical to the system's \ctype{wchar_t}. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3132 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3133 \begin{cfuncdesc}{PyObject*}{PyUnicode_FromWideChar}{const wchar_t *w, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3134 int size} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3135 Create a Unicode Object from the \ctype{whcar_t} buffer \var{w} of the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3136 given size. Returns \NULL{} on failure. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3137 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3138 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3139 \begin{cfuncdesc}{int}{PyUnicode_AsWideChar}{PyUnicodeObject *unicode, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3140 wchar_t *w, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3141 int size} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3142 Copies the Unicode Object contents into the \ctype{whcar_t} buffer |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3143 \var{w}. At most \var{size} \ctype{whcar_t} characters are copied. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3144 Returns the number of \ctype{whcar_t} characters copied or -1 in case |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3145 of an error. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3146 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3147 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3148 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3149 \subsubsection{Builtin Codecs \label{builtinCodecs}} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3150 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3151 Python provides a set of builtin codecs which are written in C |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3152 for speed. All of these codecs are directly usable via the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3153 following functions. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3154 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3155 Many of the following APIs take two arguments encoding and |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3156 errors. These parameters encoding and errors have the same semantics |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3157 as the ones of the builtin unicode() Unicode object constructor. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3158 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3159 Setting encoding to NULL causes the default encoding to be used which |
|
19735
f56c91820fae
Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents:
19705
diff
changeset
|
3160 is \ASCII{}. The file system calls should use |
|
f56c91820fae
Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents:
19705
diff
changeset
|
3161 \var{Py_FileSystemDefaultEncoding} as the encoding for file |
|
f56c91820fae
Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents:
19705
diff
changeset
|
3162 names. This variable should be treated as read-only: On some systems, |
|
f56c91820fae
Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents:
19705
diff
changeset
|
3163 it will be a pointer to a static string, on others, it will change at |
|
f56c91820fae
Patch #449815: Set filesystemencoding based on CODESET.
Martin v. Löwis <martin@v.loewis.de>
parents:
19705
diff
changeset
|
3164 run-time, e.g. when the application invokes setlocale. |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3165 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3166 Error handling is set by errors which may also be set to NULL meaning |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3167 to use the default handling defined for the codec. Default error |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3168 handling for all builtin codecs is ``strict'' (ValueErrors are raised). |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3169 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3170 The codecs all use a similar interface. Only deviation from the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3171 following generic ones are documented for simplicity. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3172 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3173 % --- Generic Codecs ----------------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3174 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3175 These are the generic codec APIs: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3176 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3177 \begin{cfuncdesc}{PyObject*}{PyUnicode_Decode}{const char *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3178 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3179 const char *encoding, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3180 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3181 Create a Unicode object by decoding \var{size} bytes of the encoded |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3182 string \var{s}. \var{encoding} and \var{errors} have the same meaning |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3183 as the parameters of the same name in the unicode() builtin |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3184 function. The codec to be used is looked up using the Python codec |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3185 registry. Returns \NULL{} in case an exception was raised by the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3186 codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3187 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3188 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3189 \begin{cfuncdesc}{PyObject*}{PyUnicode_Encode}{const Py_UNICODE *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3190 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3191 const char *encoding, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3192 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3193 Encodes the \ctype{Py_UNICODE} buffer of the given size and returns a |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3194 Python string object. \var{encoding} and \var{errors} have the same |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3195 meaning as the parameters of the same name in the Unicode .encode() |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3196 method. The codec to be used is looked up using the Python codec |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3197 registry. Returns \NULL{} in case an exception was raised by the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3198 codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3199 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3200 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3201 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsEncodedString}{PyObject *unicode, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3202 const char *encoding, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3203 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3204 Encodes a Unicode object and returns the result as Python string |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3205 object. \var{encoding} and \var{errors} have the same meaning as the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3206 parameters of the same name in the Unicode .encode() method. The codec |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3207 to be used is looked up using the Python codec registry. Returns |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3208 \NULL{} in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3209 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3210 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3211 % --- UTF-8 Codecs ------------------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3212 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3213 These are the UTF-8 codec APIs: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3214 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3215 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF8}{const char *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3216 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3217 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3218 Creates a Unicode object by decoding \var{size} bytes of the UTF-8 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3219 encoded string \var{s}. Returns \NULL{} in case an exception was |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3220 raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3221 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3222 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3223 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF8}{const Py_UNICODE *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3224 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3225 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3226 Encodes the \ctype{Py_UNICODE} buffer of the given size using UTF-8 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3227 and returns a Python string object. Returns \NULL{} in case an |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3228 exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3229 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3230 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3231 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF8String}{PyObject *unicode} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3232 Encodes a Unicode objects using UTF-8 and returns the result as Python |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3233 string object. Error handling is ``strict''. Returns |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3234 \NULL{} in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3235 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3236 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3237 % --- UTF-16 Codecs ------------------------------------------------------ */ |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3238 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3239 These are the UTF-16 codec APIs: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3240 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3241 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUTF16}{const char *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3242 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3243 const char *errors, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3244 int *byteorder} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3245 Decodes \var{length} bytes from a UTF-16 encoded buffer string and |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3246 returns the corresponding Unicode object. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3247 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3248 \var{errors} (if non-NULL) defines the error handling. It defaults |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3249 to ``strict''. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3250 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3251 If \var{byteorder} is non-\NULL{}, the decoder starts decoding using |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3252 the given byte order: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3253 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3254 \begin{verbatim} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3255 *byteorder == -1: little endian |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3256 *byteorder == 0: native order |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3257 *byteorder == 1: big endian |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3258 \end{verbatim} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3259 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3260 and then switches according to all byte order marks (BOM) it finds in |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3261 the input data. BOM marks are not copied into the resulting Unicode |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3262 string. After completion, \var{*byteorder} is set to the current byte |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3263 order at the end of input data. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3264 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3265 If \var{byteorder} is \NULL{}, the codec starts in native order mode. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3266 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3267 Returns \NULL{} in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3268 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3269 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3270 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUTF16}{const Py_UNICODE *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3271 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3272 const char *errors, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3273 int byteorder} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3274 Returns a Python string object holding the UTF-16 encoded value of the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3275 Unicode data in \var{s}. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3276 |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
3277 If \var{byteorder} is not \code{0}, output is written according to the |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3278 following byte order: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3279 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3280 \begin{verbatim} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3281 byteorder == -1: little endian |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3282 byteorder == 0: native byte order (writes a BOM mark) |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3283 byteorder == 1: big endian |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3284 \end{verbatim} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3285 |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
3286 If byteorder is \code{0}, the output string will always start with the |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3287 Unicode BOM mark (U+FEFF). In the other two modes, no BOM mark is |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3288 prepended. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3289 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3290 Note that \ctype{Py_UNICODE} data is being interpreted as UTF-16 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3291 reduced to UCS-2. This trick makes it possible to add full UTF-16 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3292 capabilities at a later point without comprimising the APIs. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3293 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3294 Returns \NULL{} in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3295 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3296 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3297 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUTF16String}{PyObject *unicode} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3298 Returns a Python string using the UTF-16 encoding in native byte |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3299 order. The string always starts with a BOM mark. Error handling is |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3300 ``strict''. Returns \NULL{} in case an exception was raised by the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3301 codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3302 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3303 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3304 % --- Unicode-Escape Codecs ---------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3305 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3306 These are the ``Unicode Esacpe'' codec APIs: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3307 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3308 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeUnicodeEscape}{const char *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3309 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3310 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3311 Creates a Unicode object by decoding \var{size} bytes of the Unicode-Esacpe |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3312 encoded string \var{s}. Returns \NULL{} in case an exception was |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3313 raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3314 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3315 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3316 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeUnicodeEscape}{const Py_UNICODE *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3317 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3318 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3319 Encodes the \ctype{Py_UNICODE} buffer of the given size using Unicode-Escape |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3320 and returns a Python string object. Returns \NULL{} in case an |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3321 exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3322 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3323 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3324 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsUnicodeEscapeString}{PyObject *unicode} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3325 Encodes a Unicode objects using Unicode-Escape and returns the result |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3326 as Python string object. Error handling is ``strict''. Returns |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3327 \NULL{} in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3328 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3329 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3330 % --- Raw-Unicode-Escape Codecs ------------------------------------------ |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3331 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3332 These are the ``Raw Unicode Esacpe'' codec APIs: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3333 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3334 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeRawUnicodeEscape}{const char *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3335 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3336 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3337 Creates a Unicode object by decoding \var{size} bytes of the Raw-Unicode-Esacpe |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3338 encoded string \var{s}. Returns \NULL{} in case an exception was |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3339 raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3340 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3341 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3342 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeRawUnicodeEscape}{const Py_UNICODE *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3343 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3344 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3345 Encodes the \ctype{Py_UNICODE} buffer of the given size using Raw-Unicode-Escape |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3346 and returns a Python string object. Returns \NULL{} in case an |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3347 exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3348 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3349 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3350 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsRawUnicodeEscapeString}{PyObject *unicode} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3351 Encodes a Unicode objects using Raw-Unicode-Escape and returns the result |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3352 as Python string object. Error handling is ``strict''. Returns |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3353 \NULL{} in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3354 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3355 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3356 % --- Latin-1 Codecs ----------------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3357 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3358 These are the Latin-1 codec APIs: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3359 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3360 Latin-1 corresponds to the first 256 Unicode ordinals and only these |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3361 are accepted by the codecs during encoding. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3362 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3363 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeLatin1}{const char *s, |
| 12947 | 3364 int size, |
| 3365 const char *errors} | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3366 Creates a Unicode object by decoding \var{size} bytes of the Latin-1 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3367 encoded string \var{s}. Returns \NULL{} in case an exception was |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3368 raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3369 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3370 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3371 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeLatin1}{const Py_UNICODE *s, |
| 12947 | 3372 int size, |
| 3373 const char *errors} | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3374 Encodes the \ctype{Py_UNICODE} buffer of the given size using Latin-1 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3375 and returns a Python string object. Returns \NULL{} in case an |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3376 exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3377 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3378 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3379 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsLatin1String}{PyObject *unicode} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3380 Encodes a Unicode objects using Latin-1 and returns the result as |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3381 Python string object. Error handling is ``strict''. Returns |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3382 \NULL{} in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3383 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3384 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3385 % --- ASCII Codecs ------------------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3386 |
| 12947 | 3387 These are the \ASCII{} codec APIs. Only 7-bit \ASCII{} data is |
| 3388 accepted. All other codes generate errors. | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3389 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3390 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeASCII}{const char *s, |
| 12947 | 3391 int size, |
| 3392 const char *errors} | |
| 3393 Creates a Unicode object by decoding \var{size} bytes of the | |
| 3394 \ASCII{} encoded string \var{s}. Returns \NULL{} in case an exception | |
| 3395 was raised by the codec. | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3396 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3397 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3398 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeASCII}{const Py_UNICODE *s, |
| 12947 | 3399 int size, |
| 3400 const char *errors} | |
| 3401 Encodes the \ctype{Py_UNICODE} buffer of the given size using | |
| 3402 \ASCII{} and returns a Python string object. Returns \NULL{} in case | |
| 3403 an exception was raised by the codec. | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3404 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3405 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3406 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsASCIIString}{PyObject *unicode} |
| 12947 | 3407 Encodes a Unicode objects using \ASCII{} and returns the result as Python |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3408 string object. Error handling is ``strict''. Returns |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3409 \NULL{} in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3410 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3411 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3412 % --- Character Map Codecs ----------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3413 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3414 These are the mapping codec APIs: |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3415 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3416 This codec is special in that it can be used to implement many |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3417 different codecs (and this is in fact what was done to obtain most of |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3418 the standard codecs included in the \module{encodings} package). The |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3419 codec uses mapping to encode and decode characters. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3420 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3421 Decoding mappings must map single string characters to single Unicode |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3422 characters, integers (which are then interpreted as Unicode ordinals) |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3423 or None (meaning "undefined mapping" and causing an error). |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3424 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3425 Encoding mappings must map single Unicode characters to single string |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3426 characters, integers (which are then interpreted as Latin-1 ordinals) |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3427 or None (meaning "undefined mapping" and causing an error). |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3428 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3429 The mapping objects provided must only support the __getitem__ mapping |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3430 interface. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3431 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3432 If a character lookup fails with a LookupError, the character is |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3433 copied as-is meaning that its ordinal value will be interpreted as |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3434 Unicode or Latin-1 ordinal resp. Because of this, mappings only need |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3435 to contain those mappings which map characters to different code |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3436 points. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3437 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3438 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeCharmap}{const char *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3439 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3440 PyObject *mapping, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3441 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3442 Creates a Unicode object by decoding \var{size} bytes of the encoded |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3443 string \var{s} using the given \var{mapping} object. Returns \NULL{} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3444 in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3445 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3446 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3447 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeCharmap}{const Py_UNICODE *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3448 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3449 PyObject *mapping, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3450 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3451 Encodes the \ctype{Py_UNICODE} buffer of the given size using the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3452 given \var{mapping} object and returns a Python string object. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3453 Returns \NULL{} in case an exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3454 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3455 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3456 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsCharmapString}{PyObject *unicode, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3457 PyObject *mapping} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3458 Encodes a Unicode objects using the given \var{mapping} object and |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3459 returns the result as Python string object. Error handling is |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3460 ``strict''. Returns \NULL{} in case an exception was raised by the |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3461 codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3462 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3463 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3464 The following codec API is special in that maps Unicode to Unicode. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3465 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3466 \begin{cfuncdesc}{PyObject*}{PyUnicode_TranslateCharmap}{const Py_UNICODE *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3467 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3468 PyObject *table, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3469 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3470 Translates a \ctype{Py_UNICODE} buffer of the given length by applying |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3471 a character mapping \var{table} to it and returns the resulting |
| 12947 | 3472 Unicode object. Returns \NULL{} when an exception was raised by the |
| 3473 codec. | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3474 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3475 The \var{mapping} table must map Unicode ordinal integers to Unicode |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3476 ordinal integers or None (causing deletion of the character). |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3477 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3478 Mapping tables must only provide the __getitem__ interface, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3479 e.g. dictionaries or sequences. Unmapped character ordinals (ones |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3480 which cause a LookupError) are left untouched and are copied as-is. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3481 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3482 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3483 % --- MBCS codecs for Windows -------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3484 |
| 12947 | 3485 These are the MBCS codec APIs. They are currently only available on |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3486 Windows and use the Win32 MBCS converters to implement the |
| 12947 | 3487 conversions. Note that MBCS (or DBCS) is a class of encodings, not |
| 3488 just one. The target encoding is defined by the user settings on the | |
| 3489 machine running the codec. | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3490 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3491 \begin{cfuncdesc}{PyObject*}{PyUnicode_DecodeMBCS}{const char *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3492 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3493 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3494 Creates a Unicode object by decoding \var{size} bytes of the MBCS |
| 12947 | 3495 encoded string \var{s}. Returns \NULL{} in case an exception was |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3496 raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3497 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3498 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3499 \begin{cfuncdesc}{PyObject*}{PyUnicode_EncodeMBCS}{const Py_UNICODE *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3500 int size, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3501 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3502 Encodes the \ctype{Py_UNICODE} buffer of the given size using MBCS |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3503 and returns a Python string object. Returns \NULL{} in case an |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3504 exception was raised by the codec. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3505 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3506 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3507 \begin{cfuncdesc}{PyObject*}{PyUnicode_AsMBCSString}{PyObject *unicode} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3508 Encodes a Unicode objects using MBCS and returns the result as Python |
| 12947 | 3509 string object. Error handling is ``strict''. Returns \NULL{} in case |
| 3510 an exception was raised by the codec. | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3511 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3512 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3513 % --- Methods & Slots ---------------------------------------------------- |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3514 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3515 \subsubsection{Methods and Slot Functions \label{unicodeMethodsAndSlots}} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3516 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3517 The following APIs are capable of handling Unicode objects and strings |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3518 on input (we refer to them as strings in the descriptions) and return |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3519 Unicode objects or integers as apporpriate. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3520 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3521 They all return \NULL{} or -1 in case an exception occurrs. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3522 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3523 \begin{cfuncdesc}{PyObject*}{PyUnicode_Concat}{PyObject *left, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3524 PyObject *right} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3525 Concat two strings giving a new Unicode string. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3526 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3527 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3528 \begin{cfuncdesc}{PyObject*}{PyUnicode_Split}{PyObject *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3529 PyObject *sep, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3530 int maxsplit} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3531 Split a string giving a list of Unicode strings. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3532 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3533 If sep is NULL, splitting will be done at all whitespace |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3534 substrings. Otherwise, splits occur at the given separator. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3535 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3536 At most maxsplit splits will be done. If negative, no limit is set. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3537 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3538 Separators are not included in the resulting list. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3539 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3540 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3541 \begin{cfuncdesc}{PyObject*}{PyUnicode_Splitlines}{PyObject *s, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3542 int maxsplit} |
| 12947 | 3543 Split a Unicode string at line breaks, returning a list of Unicode |
| 3544 strings. CRLF is considered to be one line break. The Line break | |
| 3545 characters are not included in the resulting strings. | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3546 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3547 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3548 \begin{cfuncdesc}{PyObject*}{PyUnicode_Translate}{PyObject *str, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3549 PyObject *table, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3550 const char *errors} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3551 Translate a string by applying a character mapping table to it and |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3552 return the resulting Unicode object. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3553 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3554 The mapping table must map Unicode ordinal integers to Unicode ordinal |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3555 integers or None (causing deletion of the character). |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3556 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3557 Mapping tables must only provide the __getitem__ interface, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3558 e.g. dictionaries or sequences. Unmapped character ordinals (ones |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3559 which cause a LookupError) are left untouched and are copied as-is. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3560 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3561 \var{errors} has the usual meaning for codecs. It may be \NULL{} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3562 which indicates to use the default error handling. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3563 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3564 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3565 \begin{cfuncdesc}{PyObject*}{PyUnicode_Join}{PyObject *separator, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3566 PyObject *seq} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3567 Join a sequence of strings using the given separator and return |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3568 the resulting Unicode string. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3569 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3570 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3571 \begin{cfuncdesc}{PyObject*}{PyUnicode_Tailmatch}{PyObject *str, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3572 PyObject *substr, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3573 int start, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3574 int end, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3575 int direction} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3576 Return 1 if \var{substr} matches \var{str}[\var{start}:\var{end}] at |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3577 the given tail end (\var{direction} == -1 means to do a prefix match, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3578 \var{direction} == 1 a suffix match), 0 otherwise. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3579 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3580 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3581 \begin{cfuncdesc}{PyObject*}{PyUnicode_Find}{PyObject *str, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3582 PyObject *substr, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3583 int start, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3584 int end, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3585 int direction} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3586 Return the first position of \var{substr} in |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3587 \var{str}[\var{start}:\var{end}] using the given \var{direction} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3588 (\var{direction} == 1 means to do a forward search, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3589 \var{direction} == -1 a backward search), 0 otherwise. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3590 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3591 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3592 \begin{cfuncdesc}{PyObject*}{PyUnicode_Count}{PyObject *str, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3593 PyObject *substr, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3594 int start, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3595 int end} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3596 Count the number of occurrences of \var{substr} in |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3597 \var{str}[\var{start}:\var{end}] |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3598 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3599 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3600 \begin{cfuncdesc}{PyObject*}{PyUnicode_Replace}{PyObject *str, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3601 PyObject *substr, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3602 PyObject *replstr, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3603 int maxcount} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3604 Replace at most \var{maxcount} occurrences of \var{substr} in |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3605 \var{str} with \var{replstr} and return the resulting Unicode object. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3606 \var{maxcount} == -1 means: replace all occurrences. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3607 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3608 |
| 12947 | 3609 \begin{cfuncdesc}{int}{PyUnicode_Compare}{PyObject *left, PyObject *right} |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3610 Compare two strings and return -1, 0, 1 for less than, equal, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3611 greater than resp. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3612 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3613 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3614 \begin{cfuncdesc}{PyObject*}{PyUnicode_Format}{PyObject *format, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3615 PyObject *args} |
| 12947 | 3616 Returns a new string object from \var{format} and \var{args}; this is |
| 3617 analogous to \code{\var{format} \%\ \var{args}}. The | |
| 3618 \var{args} argument must be a tuple. | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3619 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3620 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3621 \begin{cfuncdesc}{int}{PyUnicode_Contains}{PyObject *container, |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3622 PyObject *element} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3623 Checks whether \var{element} is contained in \var{container} and |
| 12947 | 3624 returns true or false accordingly. |
| 3625 | |
| 3626 \var{element} has to coerce to a one element Unicode string. \code{-1} is | |
|
12258
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3627 returned in case of an error. |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3628 \end{cfuncdesc} |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3629 |
|
65bc5eaf47ce
Marc-Andre Lemburg <mal@lemburg.com>:
Fred Drake <fdrake@acm.org>
parents:
12222
diff
changeset
|
3630 |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3631 \subsection{Buffer Objects \label{bufferObjects}} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3632 \sectionauthor{Greg Stein}{gstein@lyra.org} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3633 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3634 \obindex{buffer} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3635 Python objects implemented in C can export a group of functions called |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3636 the ``buffer\index{buffer interface} interface.'' These functions can |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3637 be used by an object to expose its data in a raw, byte-oriented |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3638 format. Clients of the object can use the buffer interface to access |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3639 the object data directly, without needing to copy it first. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3640 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3641 Two examples of objects that support |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3642 the buffer interface are strings and arrays. The string object exposes |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3643 the character contents in the buffer interface's byte-oriented |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3644 form. An array can also expose its contents, but it should be noted |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3645 that array elements may be multi-byte values. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3646 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3647 An example user of the buffer interface is the file object's |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3648 \method{write()} method. Any object that can export a series of bytes |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3649 through the buffer interface can be written to a file. There are a |
|
18785
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
3650 number of format codes to \cfunction{PyArg_ParseTuple()} that operate |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3651 against an object's buffer interface, returning data from the target |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3652 object. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3653 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3654 More information on the buffer interface is provided in the section |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3655 ``Buffer Object Structures'' (section \ref{buffer-structs}), under |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3656 the description for \ctype{PyBufferProcs}\ttindex{PyBufferProcs}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3657 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3658 A ``buffer object'' is defined in the \file{bufferobject.h} header |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3659 (included by \file{Python.h}). These objects look very similar to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3660 string objects at the Python programming level: they support slicing, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3661 indexing, concatenation, and some other standard string |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3662 operations. However, their data can come from one of two sources: from |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3663 a block of memory, or from another object which exports the buffer |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3664 interface. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3665 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3666 Buffer objects are useful as a way to expose the data from another |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3667 object's buffer interface to the Python programmer. They can also be |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3668 used as a zero-copy slicing mechanism. Using their ability to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3669 reference a block of memory, it is possible to expose any data to the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3670 Python programmer quite easily. The memory could be a large, constant |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3671 array in a C extension, it could be a raw block of memory for |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3672 manipulation before passing to an operating system library, or it |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3673 could be used to pass around structured data in its native, in-memory |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3674 format. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3675 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3676 \begin{ctypedesc}{PyBufferObject} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3677 This subtype of \ctype{PyObject} represents a buffer object. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3678 \end{ctypedesc} |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3679 |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3680 \begin{cvardesc}{PyTypeObject}{PyBuffer_Type} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3681 The instance of \ctype{PyTypeObject} which represents the Python |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3682 buffer type; it is the same object as \code{types.BufferType} in the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3683 Python layer.\withsubitem{(in module types)}{\ttindex{BufferType}}. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3684 \end{cvardesc} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3685 |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3686 \begin{cvardesc}{int}{Py_END_OF_BUFFER} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3687 This constant may be passed as the \var{size} parameter to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3688 \cfunction{PyBuffer_FromObject()} or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3689 \cfunction{PyBuffer_FromReadWriteObject()}. It indicates that the new |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3690 \ctype{PyBufferObject} should refer to \var{base} object from the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3691 specified \var{offset} to the end of its exported buffer. Using this |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3692 enables the caller to avoid querying the \var{base} object for its |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3693 length. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3694 \end{cvardesc} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3695 |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3696 \begin{cfuncdesc}{int}{PyBuffer_Check}{PyObject *p} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3697 Return true if the argument has type \cdata{PyBuffer_Type}. |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3698 \end{cfuncdesc} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3699 |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3700 \begin{cfuncdesc}{PyObject*}{PyBuffer_FromObject}{PyObject *base, |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3701 int offset, int size} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3702 Return a new read-only buffer object. This raises |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3703 \exception{TypeError} if \var{base} doesn't support the read-only |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3704 buffer protocol or doesn't provide exactly one buffer segment, or it |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3705 raises \exception{ValueError} if \var{offset} is less than zero. The |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3706 buffer will hold a reference to the \var{base} object, and the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3707 buffer's contents will refer to the \var{base} object's buffer |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3708 interface, starting as position \var{offset} and extending for |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3709 \var{size} bytes. If \var{size} is \constant{Py_END_OF_BUFFER}, then |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3710 the new buffer's contents extend to the length of the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3711 \var{base} object's exported buffer data. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3712 \end{cfuncdesc} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3713 |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3714 \begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteObject}{PyObject *base, |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3715 int offset, |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3716 int size} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3717 Return a new writable buffer object. Parameters and exceptions are |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3718 similar to those for \cfunction{PyBuffer_FromObject()}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3719 If the \var{base} object does not export the writeable buffer |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3720 protocol, then \exception{TypeError} is raised. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3721 \end{cfuncdesc} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3722 |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3723 \begin{cfuncdesc}{PyObject*}{PyBuffer_FromMemory}{void *ptr, int size} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3724 Return a new read-only buffer object that reads from a specified |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3725 location in memory, with a specified size. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3726 The caller is responsible for ensuring that the memory buffer, passed |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3727 in as \var{ptr}, is not deallocated while the returned buffer object |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3728 exists. Raises \exception{ValueError} if \var{size} is less than |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3729 zero. Note that \constant{Py_END_OF_BUFFER} may \emph{not} be passed |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3730 for the \var{size} parameter; \exception{ValueError} will be raised in |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3731 that case. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3732 \end{cfuncdesc} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3733 |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3734 \begin{cfuncdesc}{PyObject*}{PyBuffer_FromReadWriteMemory}{void *ptr, int size} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3735 Similar to \cfunction{PyBuffer_FromMemory()}, but the returned buffer |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3736 is writable. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3737 \end{cfuncdesc} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3738 |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3739 \begin{cfuncdesc}{PyObject*}{PyBuffer_New}{int size} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3740 Returns a new writable buffer object that maintains its own memory |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3741 buffer of \var{size} bytes. \exception{ValueError} is returned if |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3742 \var{size} is not zero or positive. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3743 \end{cfuncdesc} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
3744 |
|
8109
2e49bc89fafa
Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents:
8057
diff
changeset
|
3745 |
| 10163 | 3746 \subsection{Tuple Objects \label{tupleObjects}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3747 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3748 \obindex{tuple} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3749 \begin{ctypedesc}{PyTupleObject} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
3750 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
|
3751 \end{ctypedesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3752 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3753 \begin{cvardesc}{PyTypeObject}{PyTuple_Type} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3754 This instance of \ctype{PyTypeObject} represents the Python tuple |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3755 type; it is the same object as \code{types.TupleType} in the Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3756 layer.\withsubitem{(in module types)}{\ttindex{TupleType}}. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3757 \end{cvardesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3758 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3759 \begin{cfuncdesc}{int}{PyTuple_Check}{PyObject *p} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
3760 Return true if \var{p} is a tuple object or an instance of a subtype |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
3761 of the tuple type. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
3762 \versionchanged[Allowed subtypes to be accepted]{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
3763 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
3764 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
3765 \begin{cfuncdesc}{int}{PyTuple_CheckExact}{PyObject *p} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
3766 Return true if \var{p} is a tuple object, but not an instance of |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
3767 a subtype of the tuple type. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
3768 \versionadded{2.2} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3769 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3770 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3771 \begin{cfuncdesc}{PyObject*}{PyTuple_New}{int len} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3772 Return a new tuple object of size \var{len}, or \NULL{} on failure. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3773 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3774 |
|
16577
068cb8494b7b
PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents:
16439
diff
changeset
|
3775 \begin{cfuncdesc}{int}{PyTuple_Size}{PyObject *p} |
| 7308 | 3776 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
|
3777 of that tuple. |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3778 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3779 |
|
19399
e851e6148ad8
Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents:
19301
diff
changeset
|
3780 \begin{cfuncdesc}{int}{PyTuple_GET_SIZE}{PyObject *p} |
|
e851e6148ad8
Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents:
19301
diff
changeset
|
3781 Return the size of the tuple \var{p}, which must be non-\NULL{} and |
|
e851e6148ad8
Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents:
19301
diff
changeset
|
3782 point to a tuple; no error checking is performed. |
|
e851e6148ad8
Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents:
19301
diff
changeset
|
3783 \end{cfuncdesc} |
|
e851e6148ad8
Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents:
19301
diff
changeset
|
3784 |
|
16577
068cb8494b7b
PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents:
16439
diff
changeset
|
3785 \begin{cfuncdesc}{PyObject*}{PyTuple_GetItem}{PyObject *p, int pos} |
| 7308 | 3786 Returns the object at position \var{pos} in the tuple pointed |
| 3787 to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3788 sets an \exception{IndexError} exception. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3789 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3790 |
|
16577
068cb8494b7b
PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents:
16439
diff
changeset
|
3791 \begin{cfuncdesc}{PyObject*}{PyTuple_GET_ITEM}{PyObject *p, int pos} |
|
17981
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3792 Like \cfunction{PyTuple_GetItem()}, but does no checking of its |
|
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3793 arguments. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3794 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3795 |
|
16577
068cb8494b7b
PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents:
16439
diff
changeset
|
3796 \begin{cfuncdesc}{PyObject*}{PyTuple_GetSlice}{PyObject *p, |
|
068cb8494b7b
PyTuple_*() functions take PyObject* parameters, not PyTupleObject* values.
Fred Drake <fdrake@acm.org>
parents:
16439
diff
changeset
|
3797 int low, int high} |
| 7308 | 3798 Takes a slice of the tuple pointed to by \var{p} from |
| 3799 \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
|
3800 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3801 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3802 \begin{cfuncdesc}{int}{PyTuple_SetItem}{PyObject *p, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3803 int pos, PyObject *o} |
| 7308 | 3804 Inserts a reference to object \var{o} at position \var{pos} of |
| 3805 the tuple pointed to by \var{p}. It returns \code{0} on success. | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3806 \strong{Note:} This function ``steals'' a reference to \var{o}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3807 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3808 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3809 \begin{cfuncdesc}{void}{PyTuple_SET_ITEM}{PyObject *p, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3810 int pos, PyObject *o} |
|
17981
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3811 Like \cfunction{PyTuple_SetItem()}, but does no error checking, and |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3812 should \emph{only} be used to fill in brand new tuples. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3813 \strong{Note:} This function ``steals'' a reference to \var{o}. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3814 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3815 |
|
17981
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3816 \begin{cfuncdesc}{int}{_PyTuple_Resize}{PyObject **p, int newsize} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3817 Can be used to resize a tuple. \var{newsize} will be the new length |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3818 of the tuple. Because tuples are \emph{supposed} to be immutable, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3819 this should only be used if there is only one reference to the object. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3820 Do \emph{not} use this if the tuple may already be known to some other |
|
17981
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3821 part of the code. The tuple will always grow or shrink at the end. |
|
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3822 Think of this as destroying the old tuple and creating a new one, only |
|
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3823 more efficiently. Returns \code{0} on success. Client code should |
|
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3824 never assume that the resulting value of \code{*\var{p}} will be the |
|
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3825 same as before calling this function. If the object referenced by |
|
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3826 \code{*\var{p}} is replaced, the original \code{*\var{p}} is |
|
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3827 destroyed. On failure, returns \code{-1} and sets \code{*\var{p}} to |
|
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3828 \NULL, and raises \exception{MemoryError} or \exception{SystemError}. |
|
a2b996c716a1
Do not start API descriptions with "Does the same, but ..." -- actually
Fred Drake <fdrake@acm.org>
parents:
17877
diff
changeset
|
3829 \versionchanged[Removed unused third parameter, \var{last_is_sticky}]{2.2} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3830 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3831 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3832 |
| 10163 | 3833 \subsection{List Objects \label{listObjects}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3834 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3835 \obindex{list} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3836 \begin{ctypedesc}{PyListObject} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
3837 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
|
3838 \end{ctypedesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3839 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3840 \begin{cvardesc}{PyTypeObject}{PyList_Type} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3841 This instance of \ctype{PyTypeObject} represents the Python list |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3842 type. This is the same object as \code{types.ListType}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3843 \withsubitem{(in module types)}{\ttindex{ListType}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3844 \end{cvardesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3845 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3846 \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
|
3847 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
|
3848 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3849 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3850 \begin{cfuncdesc}{PyObject*}{PyList_New}{int len} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3851 Returns a new list of length \var{len} on success, or \NULL{} on |
|
8057
5aacdd097941
Some patches by Drew Csillag; plus a few of my own uncommitted changes.
Guido van Rossum <guido@python.org>
parents:
8029
diff
changeset
|
3852 failure. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3853 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3854 |
| 7782 | 3855 \begin{cfuncdesc}{int}{PyList_Size}{PyObject *list} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3856 Returns the length of the list object in \var{list}; this is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3857 equivalent to \samp{len(\var{list})} on a list object. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3858 \bifuncindex{len} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3859 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3860 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3861 \begin{cfuncdesc}{int}{PyList_GET_SIZE}{PyObject *list} |
|
15087
a13a2acbe214
Fix a couple of places where the descriptions of *_GET_SIZE() macros said
Fred Drake <fdrake@acm.org>
parents:
15038
diff
changeset
|
3862 Macro form of \cfunction{PyList_Size()} without error checking. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3863 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3864 |
| 7782 | 3865 \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
|
3866 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
|
3867 to by \var{p}. If \var{pos} is out of bounds, returns \NULL{} and |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3868 sets an \exception{IndexError} exception. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3869 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3870 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3871 \begin{cfuncdesc}{PyObject*}{PyList_GET_ITEM}{PyObject *list, int i} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3872 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
|
3873 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3874 |
| 7782 | 3875 \begin{cfuncdesc}{int}{PyList_SetItem}{PyObject *list, int index, |
| 3876 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
|
3877 Sets the item at index \var{index} in list to \var{item}. |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
3878 Returns \code{0} on success or \code{-1} on failure. |
|
18020
e86d33081bba
Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
18000
diff
changeset
|
3879 \strong{Note:} This function ``steals'' a reference to \var{item} and |
|
e86d33081bba
Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
18000
diff
changeset
|
3880 discards a reference to an item already in the list at the affected |
|
e86d33081bba
Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
18000
diff
changeset
|
3881 position. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3882 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3883 |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
3884 \begin{cfuncdesc}{void}{PyList_SET_ITEM}{PyObject *list, int i, |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3885 PyObject *o} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3886 Macro form of \cfunction{PyList_SetItem()} without error checking. |
|
18020
e86d33081bba
Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
18000
diff
changeset
|
3887 \strong{Note:} This function ``steals'' a reference to \var{item}, |
|
e86d33081bba
Explained more differences between PyList_SetItem() and PyList_SET_ITEM().
Fred Drake <fdrake@acm.org>
parents:
18000
diff
changeset
|
3888 and, unlike \cfunction{PyList_SetItem()}, does \emph{not} discard a |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
3889 reference to any item that it being replaced; any reference in |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
3890 \var{list} at position \var{i} will be leaked. This is normally only |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
3891 used to fill in new lists where there is no previous content. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3892 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3893 |
| 7782 | 3894 \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
|
3895 PyObject *item} |
|
2e49bc89fafa
Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents:
8057
diff
changeset
|
3896 Inserts the item \var{item} into list \var{list} in front of index |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3897 \var{index}. Returns \code{0} if successful; returns \code{-1} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3898 raises an exception if unsuccessful. Analogous to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3899 \code{\var{list}.insert(\var{index}, \var{item})}. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3900 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3901 |
| 7782 | 3902 \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
|
3903 Appends the object \var{item} at the end of list \var{list}. Returns |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3904 \code{0} if successful; returns \code{-1} and sets an exception if |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3905 unsuccessful. Analogous to \code{\var{list}.append(\var{item})}. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3906 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3907 |
| 7782 | 3908 \begin{cfuncdesc}{PyObject*}{PyList_GetSlice}{PyObject *list, |
| 3909 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
|
3910 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
|
3911 \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
|
3912 exception if unsuccessful. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3913 Analogous to \code{\var{list}[\var{low}:\var{high}]}. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3914 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3915 |
| 7782 | 3916 \begin{cfuncdesc}{int}{PyList_SetSlice}{PyObject *list, |
| 3917 int low, int high, | |
| 3918 PyObject *itemlist} | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3919 Sets the slice of \var{list} between \var{low} and \var{high} to the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3920 contents of \var{itemlist}. Analogous to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3921 \code{\var{list}[\var{low}:\var{high}] = \var{itemlist}}. Returns |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3922 \code{0} on success, \code{-1} on failure. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3923 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3924 |
| 7782 | 3925 \begin{cfuncdesc}{int}{PyList_Sort}{PyObject *list} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3926 Sorts the items of \var{list} in place. Returns \code{0} on success, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3927 \code{-1} on failure. This is equivalent to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3928 \samp{\var{list}.sort()}. |
| 7782 | 3929 \end{cfuncdesc} |
| 3930 | |
| 3931 \begin{cfuncdesc}{int}{PyList_Reverse}{PyObject *list} | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3932 Reverses the items of \var{list} in place. Returns \code{0} on |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3933 success, \code{-1} on failure. This is the equivalent of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3934 \samp{\var{list}.reverse()}. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3935 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3936 |
| 7782 | 3937 \begin{cfuncdesc}{PyObject*}{PyList_AsTuple}{PyObject *list} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3938 Returns a new tuple object containing the contents of \var{list}; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3939 equivalent to \samp{tuple(\var{list})}.\bifuncindex{tuple} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3940 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3941 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3942 |
| 10163 | 3943 \section{Mapping Objects \label{mapObjects}} |
| 3944 | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3945 \obindex{mapping} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3946 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3947 |
| 10163 | 3948 \subsection{Dictionary Objects \label{dictObjects}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3949 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3950 \obindex{dictionary} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3951 \begin{ctypedesc}{PyDictObject} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
3952 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
|
3953 \end{ctypedesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3954 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3955 \begin{cvardesc}{PyTypeObject}{PyDict_Type} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3956 This instance of \ctype{PyTypeObject} represents the Python dictionary |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3957 type. This is exposed to Python programs as \code{types.DictType} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3958 \code{types.DictionaryType}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3959 \withsubitem{(in module types)}{\ttindex{DictType}\ttindex{DictionaryType}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3960 \end{cvardesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3961 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3962 \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
|
3963 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
|
3964 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3965 |
| 7782 | 3966 \begin{cfuncdesc}{PyObject*}{PyDict_New}{} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3967 Returns a new empty dictionary, or \NULL{} on failure. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3968 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3969 |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
3970 \begin{cfuncdesc}{PyObject*}{PyDictProxy_New}{PyObject *dict} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
3971 Return a proxy object for a mapping which enforces read-only |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
3972 behavior. This is normally used to create a proxy to prevent |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
3973 modification of the dictionary for non-dynamic class types. |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
3974 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
3975 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
3976 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3977 \begin{cfuncdesc}{void}{PyDict_Clear}{PyObject *p} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3978 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
|
3979 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3980 |
|
12126
e6214ad2a60c
Add PyDict_Copy() function to C API for dicts. It returns a new
Jeremy Hylton <jeremy@alum.mit.edu>
parents:
11453
diff
changeset
|
3981 \begin{cfuncdesc}{PyObject*}{PyDict_Copy}{PyObject *p} |
|
19399
e851e6148ad8
Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents:
19301
diff
changeset
|
3982 Returns a new dictionary that contains the same key-value pairs as |
|
e851e6148ad8
Document PyTuple_GET_SIZE(), removing confusing sentence from PyDict_Copy()
Fred Drake <fdrake@acm.org>
parents:
19301
diff
changeset
|
3983 \var{p}. |
|
19156
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
3984 \versionadded{1.6} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3985 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3986 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3987 \begin{cfuncdesc}{int}{PyDict_SetItem}{PyObject *p, PyObject *key, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3988 PyObject *val} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
3989 Inserts \var{value} into the dictionary \var{p} with a key of \var{key}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3990 \var{key} must be hashable; if it isn't, \exception{TypeError} will be |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
3991 raised. |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
3992 Returns \code{0} on success or \code{-1} on failure. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3993 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3994 |
|
17057
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
3995 \begin{cfuncdesc}{int}{PyDict_SetItemString}{PyObject *p, |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3996 char *key, |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
3997 PyObject *val} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
3998 Inserts \var{value} into the dictionary \var{p} using \var{key} |
| 12947 | 3999 as a key. \var{key} should be a \ctype{char*}. The key object is |
| 7308 | 4000 created using \code{PyString_FromString(\var{key})}. |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
4001 Returns \code{0} on success or \code{-1} on failure. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4002 \ttindex{PyString_FromString()} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4003 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4004 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4005 \begin{cfuncdesc}{int}{PyDict_DelItem}{PyObject *p, PyObject *key} |
| 7308 | 4006 Removes the entry in dictionary \var{p} with key \var{key}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4007 \var{key} must be hashable; if it isn't, \exception{TypeError} is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4008 raised. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4009 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4010 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4011 \begin{cfuncdesc}{int}{PyDict_DelItemString}{PyObject *p, char *key} |
| 7308 | 4012 Removes the entry in dictionary \var{p} which has a key |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4013 specified by the string \var{key}. |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
4014 Returns \code{0} on success or \code{-1} on failure. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4015 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4016 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4017 \begin{cfuncdesc}{PyObject*}{PyDict_GetItem}{PyObject *p, PyObject *key} |
| 7308 | 4018 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
|
4019 \var{key}. Returns \NULL{} if the key \var{key} is not present, but |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4020 \emph{without} setting an exception. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4021 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4022 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4023 \begin{cfuncdesc}{PyObject*}{PyDict_GetItemString}{PyObject *p, char *key} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
4024 This is the same as \cfunction{PyDict_GetItem()}, but \var{key} is |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4025 specified as a \ctype{char*}, rather than a \ctype{PyObject*}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4026 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4027 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4028 \begin{cfuncdesc}{PyObject*}{PyDict_Items}{PyObject *p} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
4029 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
|
4030 from the dictionary, as in the dictinoary method \method{items()} (see |
|
11451
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
4031 the \citetitle[../lib/lib.html]{Python Library Reference}). |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4032 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4033 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4034 \begin{cfuncdesc}{PyObject*}{PyDict_Keys}{PyObject *p} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
4035 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
|
4036 from the dictionary, as in the dictionary method \method{keys()} (see the |
|
11451
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
4037 \citetitle[../lib/lib.html]{Python Library Reference}). |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4038 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4039 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4040 \begin{cfuncdesc}{PyObject*}{PyDict_Values}{PyObject *p} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
4041 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
|
4042 from the dictionary \var{p}, as in the dictionary method |
|
11451
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
4043 \method{values()} (see the \citetitle[../lib/lib.html]{Python Library |
|
38c7444f633a
Use \citetitle and \programopt as appropriate.
Fred Drake <fdrake@acm.org>
parents:
11222
diff
changeset
|
4044 Reference}). |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4045 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4046 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4047 \begin{cfuncdesc}{int}{PyDict_Size}{PyObject *p} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4048 Returns the number of items in the dictionary. This is equivalent to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4049 \samp{len(\var{p})} on a dictionary.\bifuncindex{len} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4050 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4051 |
|
17057
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4052 \begin{cfuncdesc}{int}{PyDict_Next}{PyObject *p, int *ppos, |
|
13920
d057cd543ed9
ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents:
13592
diff
changeset
|
4053 PyObject **pkey, PyObject **pvalue} |
|
17057
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4054 Iterate over all key-value pairs in the dictionary \var{p}. The |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4055 \ctype{int} referred to by \var{ppos} must be initialized to \code{0} |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4056 prior to the first call to this function to start the iteration; the |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4057 function returns true for each pair in the dictionary, and false once |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4058 all pairs have been reported. The parameters \var{pkey} and |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4059 \var{pvalue} should either point to \ctype{PyObject*} variables that |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4060 will be filled in with each key and value, respectively, or may be |
| 17504 | 4061 \NULL. |
| 4062 | |
|
17057
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4063 For example: |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4064 |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4065 \begin{verbatim} |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4066 PyObject *key, *value; |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4067 int pos = 0; |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4068 |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4069 while (PyDict_Next(self->dict, &pos, &key, &value)) { |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4070 /* do something interesting with the values... */ |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4071 ... |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4072 } |
|
797ebb7033d7
Finally fill in the documentation for the PyDict_Next() function. It is
Fred Drake <fdrake@acm.org>
parents:
16872
diff
changeset
|
4073 \end{verbatim} |
| 17504 | 4074 |
| 4075 The dictionary \var{p} should not be mutated during iteration. It is | |
| 4076 safe (since Python 2.1) to modify the values of the keys as you | |
|
19156
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4077 iterate over the dictionary, but only so long as the set of keys does |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4078 not change. For example: |
| 17504 | 4079 |
| 4080 \begin{verbatim} | |
| 4081 PyObject *key, *value; | |
| 4082 int pos = 0; | |
| 4083 | |
| 4084 while (PyDict_Next(self->dict, &pos, &key, &value)) { | |
| 4085 int i = PyInt_AS_LONG(value) + 1; | |
| 4086 PyObject *o = PyInt_FromLong(i); | |
| 4087 if (o == NULL) | |
| 4088 return -1; | |
| 4089 if (PyDict_SetItem(self->dict, key, o) < 0) { | |
| 4090 Py_DECREF(o); | |
| 4091 return -1; | |
| 4092 } | |
| 4093 Py_DECREF(o); | |
| 4094 } | |
| 4095 \end{verbatim} | |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4096 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4097 |
|
19156
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4098 \begin{cfuncdesc}{int}{PyDict_Merge}{PyObject *a, PyObject *b, int override} |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4099 Iterate over dictionary \var{b} adding key-value pairs to dictionary |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4100 \var{a}. If \var{override} is true, existing pairs in \var{a} will be |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4101 replaced if a matching key is found in \var{b}, otherwise pairs will |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4102 only be added if there is not a matching key in \var{a}. Returns |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4103 \code{0} on success or \code{-1} if an exception was raised. |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4104 \versionadded{2.2} |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4105 \end{cfuncdesc} |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4106 |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4107 \begin{cfuncdesc}{int}{PyDict_Update}{PyObject *a, PyObject *b} |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4108 This is the same as \code{PyDict_Merge(\var{a}, \var{b}, 1)} in C, or |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4109 \code{\var{a}.update(\var{b})} in Python. Returns \code{0} on success |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4110 or \code{-1} if an exception was raised. |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4111 \versionadded{2.2} |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4112 \end{cfuncdesc} |
|
776628eea8f7
Added documentation for PyDict_Update() and PyDict_Merge().
Fred Drake <fdrake@acm.org>
parents:
19126
diff
changeset
|
4113 |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4114 |
| 10163 | 4115 \section{Other Objects \label{otherObjects}} |
| 4116 | |
| 4117 \subsection{File Objects \label{fileObjects}} | |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4118 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4119 \obindex{file} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4120 Python's built-in file objects are implemented entirely on the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4121 \ctype{FILE*} support from the C standard library. This is an |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4122 implementation detail and may change in future releases of Python. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4123 |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4124 \begin{ctypedesc}{PyFileObject} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
4125 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
|
4126 \end{ctypedesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4127 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4128 \begin{cvardesc}{PyTypeObject}{PyFile_Type} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4129 This instance of \ctype{PyTypeObject} represents the Python file |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4130 type. This is exposed to Python programs as \code{types.FileType}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4131 \withsubitem{(in module types)}{\ttindex{FileType}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4132 \end{cvardesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4133 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4134 \begin{cfuncdesc}{int}{PyFile_Check}{PyObject *p} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4135 Returns true if its argument is a \ctype{PyFileObject} or a subtype of |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4136 \ctype{PyFileObject}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4137 \versionchanged[Allowed subtypes to be accepted]{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4138 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4139 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4140 \begin{cfuncdesc}{int}{PyFile_CheckExact}{PyObject *p} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4141 Returns true if its argument is a \ctype{PyFileObject}, but not a |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4142 subtype of \ctype{PyFileObject}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4143 \versionadded{2.2} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4144 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4145 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4146 \begin{cfuncdesc}{PyObject*}{PyFile_FromString}{char *filename, char *mode} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4147 On success, returns a new file object that is opened on the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4148 file given by \var{filename}, with a file mode given by \var{mode}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4149 where \var{mode} has the same semantics as the standard C routine |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4150 \cfunction{fopen()}\ttindex{fopen()}. On failure, returns \NULL. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4151 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4152 |
| 7782 | 4153 \begin{cfuncdesc}{PyObject*}{PyFile_FromFile}{FILE *fp, |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4154 char *name, char *mode, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4155 int (*close)(FILE*)} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4156 Creates a new \ctype{PyFileObject} from the already-open standard C |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4157 file pointer, \var{fp}. The function \var{close} will be called when |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4158 the file should be closed. Returns \NULL{} on failure. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4159 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4160 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4161 \begin{cfuncdesc}{FILE*}{PyFile_AsFile}{PyFileObject *p} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4162 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
|
4163 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4164 |
| 7782 | 4165 \begin{cfuncdesc}{PyObject*}{PyFile_GetLine}{PyObject *p, int n} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4166 Equivalent to \code{\var{p}.readline(\optional{\var{n}})}, this |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4167 function reads one line from the object \var{p}. \var{p} may be a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4168 file object or any object with a \method{readline()} method. If |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4169 \var{n} is \code{0}, exactly one line is read, regardless of the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4170 length of the line. If \var{n} is greater than \code{0}, no more than |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4171 \var{n} bytes will be read from the file; a partial line can be |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4172 returned. In both cases, an empty string is returned if the end of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4173 the file is reached immediately. If \var{n} is less than \code{0}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4174 however, one line is read regardless of length, but |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4175 \exception{EOFError} is raised if the end of the file is reached |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4176 immediately. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4177 \withsubitem{(built-in exception)}{\ttindex{EOFError}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4178 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4179 |
| 7782 | 4180 \begin{cfuncdesc}{PyObject*}{PyFile_Name}{PyObject *p} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4181 Returns the name of the file specified by \var{p} as a string object. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4182 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4183 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4184 \begin{cfuncdesc}{void}{PyFile_SetBufSize}{PyFileObject *p, int n} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4185 Available on systems with \cfunction{setvbuf()}\ttindex{setvbuf()} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4186 only. This should only be called immediately after file object |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4187 creation. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4188 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4189 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4190 \begin{cfuncdesc}{int}{PyFile_SoftSpace}{PyObject *p, int newflag} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4191 This function exists for internal use by the interpreter. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4192 Sets the \member{softspace} attribute of \var{p} to \var{newflag} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4193 \withsubitem{(file attribute)}{\ttindex{softspace}}returns the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4194 previous value. \var{p} does not have to be a file object |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4195 for this function to work properly; any object is supported (thought |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4196 its only interesting if the \member{softspace} attribute can be set). |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4197 This function clears any errors, and will return \code{0} as the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4198 previous value if the attribute either does not exist or if there were |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4199 errors in retrieving it. There is no way to detect errors from this |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4200 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
|
4201 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4202 |
| 7782 | 4203 \begin{cfuncdesc}{int}{PyFile_WriteObject}{PyObject *obj, PyFileObject *p, |
| 4204 int flags} | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4205 Writes object \var{obj} to file object \var{p}. The only supported |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4206 flag for \var{flags} is \constant{Py_PRINT_RAW}\ttindex{Py_PRINT_RAW}; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4207 if given, the \function{str()} of the object is written instead of the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4208 \function{repr()}. Returns \code{0} on success or \code{-1} on |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4209 failure; the appropriate exception will be set. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4210 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4211 |
|
19126
67be3a68fde4
Remove the bogus flags parameter from the PyFile_WriteString() signature;
Fred Drake <fdrake@acm.org>
parents:
19076
diff
changeset
|
4212 \begin{cfuncdesc}{int}{PyFile_WriteString}{char *s, PyFileObject *p} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4213 Writes string \var{s} to file object \var{p}. Returns \code{0} on |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4214 success or \code{-1} on failure; the appropriate exception will be |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4215 set. |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4216 \end{cfuncdesc} |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4217 |
|
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4218 |
|
16318
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4219 \subsection{Instance Objects \label{instanceObjects}} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4220 |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4221 \obindex{instance} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4222 There are very few functions specific to instance objects. |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4223 |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4224 \begin{cvardesc}{PyTypeObject}{PyInstance_Type} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4225 Type object for class instances. |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4226 \end{cvardesc} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4227 |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4228 \begin{cfuncdesc}{int}{PyInstance_Check}{PyObject *obj} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4229 Returns true if \var{obj} is an instance. |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4230 \end{cfuncdesc} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4231 |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4232 \begin{cfuncdesc}{PyObject*}{PyInstance_New}{PyObject *class, |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4233 PyObject *arg, |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4234 PyObject *kw} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4235 Create a new instance of a specific class. The parameters \var{arg} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4236 and \var{kw} are used as the positional and keyword parameters to |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4237 the object's constructor. |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4238 \end{cfuncdesc} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4239 |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4240 \begin{cfuncdesc}{PyObject*}{PyInstance_NewRaw}{PyObject *class, |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4241 PyObject *dict} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4242 Create a new instance of a specific class without calling it's |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4243 constructor. \var{class} is the class of new object. The |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4244 \var{dict} parameter will be used as the object's \member{__dict__}; |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4245 if \NULL, a new dictionary will be created for the instance. |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4246 \end{cfuncdesc} |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4247 |
|
17cac70cae76
Document the PyInstance_*() functions and data.
Fred Drake <fdrake@acm.org>
parents:
16053
diff
changeset
|
4248 |
|
19775
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4249 \subsection{Method Objects \label{method-objects}} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4250 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4251 \obindex{method} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4252 There are some useful functions that are useful for working with |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4253 method objects. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4254 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4255 \begin{cvardesc}{PyTypeObject}{PyMethod_Type} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4256 This instance of \ctype{PyTypeObject} represents the Python method |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4257 type. This is exposed to Python programs as \code{types.MethodType}. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4258 \withsubitem{(in module types)}{\ttindex{MethodType}} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4259 \end{cvardesc} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4260 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4261 \begin{cfuncdesc}{int}{PyMethod_Check}{PyObject *o} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4262 Return true if \var{o} is a method object (has type |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4263 \cdata{PyMethod_Type}). The parameter must not be \NULL. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4264 \end{cfuncdesc} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4265 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4266 \begin{cfuncdesc}{PyObject*}{PyMethod_New}{PyObject *func. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4267 PyObject *self, PyObject *class} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4268 Return a new method object, with \var{func} being any callable |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4269 object; this is the function that will be called when the method is |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4270 called. If this method should be bound to an instance, \var{self} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4271 should be the instance and \var{class} should be the class of |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4272 \var{self}, otherwise \var{self} should be \NULL{} and \var{class} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4273 should be the class which provides the unbound method.. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4274 \end{cfuncdesc} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4275 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4276 \begin{cfuncdesc}{PyObject*}{PyMethod_Class}{PyObject *meth} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4277 Return the class object from which the method \var{meth} was |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4278 created; if this was created from an instance, it will be the class |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4279 of the instance. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4280 \end{cfuncdesc} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4281 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4282 \begin{cfuncdesc}{PyObject*}{PyMethod_GET_CLASS}{PyObject *meth} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4283 Macro version of \cfunction{PyMethod_Class()} which avoids error |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4284 checking. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4285 \end{cfuncdesc} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4286 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4287 \begin{cfuncdesc}{PyObject*}{PyMethod_Function}{PyObject *meth} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4288 Return the function object associated with the method \var{meth}. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4289 \end{cfuncdesc} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4290 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4291 \begin{cfuncdesc}{PyObject*}{PyMethod_GET_FUNCTION}{PyObject *meth} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4292 Macro version of \cfunction{PyMethod_Function()} which avoids error |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4293 checking. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4294 \end{cfuncdesc} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4295 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4296 \begin{cfuncdesc}{PyObject*}{PyMethod_Self}{PyObject *meth} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4297 Return the instance associated with the method \var{meth} if it is |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4298 bound, otherwise return \NULL. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4299 \end{cfuncdesc} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4300 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4301 \begin{cfuncdesc}{PyObject*}{PyMethod_GET_SELF}{PyObject *meth} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4302 Macro version of \cfunction{PyMethod_Self()} which avoids error |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4303 checking. |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4304 \end{cfuncdesc} |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4305 |
|
ee12c38e46a6
Document the PyMethod_* type object, functions, and macros.
Fred Drake <fdrake@acm.org>
parents:
19771
diff
changeset
|
4306 |
| 10163 | 4307 \subsection{Module Objects \label{moduleObjects}} |
| 4308 | |
| 4309 \obindex{module} | |
| 4310 There are only a few functions special to module objects. | |
| 4311 | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4312 \begin{cvardesc}{PyTypeObject}{PyModule_Type} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4313 This instance of \ctype{PyTypeObject} represents the Python module |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4314 type. This is exposed to Python programs as \code{types.ModuleType}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4315 \withsubitem{(in module types)}{\ttindex{ModuleType}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4316 \end{cvardesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4317 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4318 \begin{cfuncdesc}{int}{PyModule_Check}{PyObject *p} |
|
20009
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4319 Returns true if \var{p} is a module object, or a subtype of a |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4320 module object. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4321 \versionchanged[Allowed subtypes to be accepted]{2.2} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4322 \end{cfuncdesc} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4323 |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4324 \begin{cfuncdesc}{int}{PyModule_CheckExact}{PyObject *p} |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4325 Returns true if \var{p} is a module object, but not a subtype of |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4326 \cdata{PyModule_Type}. |
|
0fe318a78990
Document all the Py*_CheckExact() functions.
Fred Drake <fdrake@acm.org>
parents:
19775
diff
changeset
|
4327 \versionadded{2.2} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4328 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4329 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4330 \begin{cfuncdesc}{PyObject*}{PyModule_New}{char *name} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4331 Return a new module object with the \member{__name__} attribute set to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4332 \var{name}. Only the module's \member{__doc__} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4333 \member{__name__} attributes are filled in; the caller is responsible |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4334 for providing a \member{__file__} attribute. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4335 \withsubitem{(module attribute)}{ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4336 \ttindex{__name__}\ttindex{__doc__}\ttindex{__file__}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4337 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4338 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4339 \begin{cfuncdesc}{PyObject*}{PyModule_GetDict}{PyObject *module} |
| 10163 | 4340 Return the dictionary object that implements \var{module}'s namespace; |
| 4341 this object is the same as the \member{__dict__} attribute of the | |
| 4342 module object. This function never fails. | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4343 \withsubitem{(module attribute)}{\ttindex{__dict__}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4344 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4345 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4346 \begin{cfuncdesc}{char*}{PyModule_GetName}{PyObject *module} |
| 10163 | 4347 Return \var{module}'s \member{__name__} value. If the module does not |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4348 provide one, or if it is not a string, \exception{SystemError} is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4349 raised and \NULL{} is returned. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4350 \withsubitem{(module attribute)}{\ttindex{__name__}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4351 \withsubitem{(built-in exception)}{\ttindex{SystemError}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4352 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4353 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4354 \begin{cfuncdesc}{char*}{PyModule_GetFilename}{PyObject *module} |
| 10163 | 4355 Return the name of the file from which \var{module} was loaded using |
| 4356 \var{module}'s \member{__file__} attribute. If this is not defined, | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4357 or if it is not a string, raise \exception{SystemError} and return |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4358 \NULL. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4359 \withsubitem{(module attribute)}{\ttindex{__file__}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4360 \withsubitem{(built-in exception)}{\ttindex{SystemError}} |
| 10163 | 4361 \end{cfuncdesc} |
| 4362 | |
|
14782
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4363 \begin{cfuncdesc}{int}{PyModule_AddObject}{PyObject *module, |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4364 char *name, PyObject *value} |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4365 Add an object to \var{module} as \var{name}. This is a convenience |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4366 function which can be used from the module's initialization function. |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4367 This steals a reference to \var{value}. Returns \code{-1} on error, |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4368 \code{0} on success. |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4369 \versionadded{2.0} |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4370 \end{cfuncdesc} |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4371 |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4372 \begin{cfuncdesc}{int}{PyModule_AddIntConstant}{PyObject *module, |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4373 char *name, int value} |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4374 Add an integer constant to \var{module} as \var{name}. This convenience |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4375 function can be used from the module's initialization function. |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4376 Returns \code{-1} on error, \code{0} on success. |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4377 \versionadded{2.0} |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4378 \end{cfuncdesc} |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4379 |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4380 \begin{cfuncdesc}{int}{PyModule_AddStringConstant}{PyObject *module, |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4381 char *name, char *value} |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4382 Add a string constant to \var{module} as \var{name}. This convenience |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4383 function can be used from the module's initialization function. The |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4384 string \var{value} must be null-terminated. Returns \code{-1} on |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4385 error, \code{0} on success. |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4386 \versionadded{2.0} |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4387 \end{cfuncdesc} |
|
3c01f921c453
Added documentation for the new PyModule_*() convenience functions.
Fred Drake <fdrake@acm.org>
parents:
14769
diff
changeset
|
4388 |
| 10163 | 4389 |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4390 \subsection{Iterator Objects \label{iterator-objects}} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4391 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4392 Python provides two general-purpose iterator objects. The first, a |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4393 sequence iterator, works with an arbitrary sequence supporting the |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4394 \method{__getitem__()} method. The second works with a callable |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4395 object and a sentinel value, calling the callable for each item in the |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4396 sequence, and ending the iteration when the sentinel value is |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4397 returned. |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4398 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4399 \begin{cvardesc}{PyTypeObject}{PySeqIter_Type} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4400 Type object for iterator objects returned by |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4401 \cfunction{PySeqIter_New()} and the one-argument form of the |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4402 \function{iter()} built-in function for built-in sequence types. |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4403 \versionadded{2.2} |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4404 \end{cvardesc} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4405 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4406 \begin{cfuncdesc}{int}{PySeqIter_Check}{op} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4407 Return true if the type of \var{op} is \cdata{PySeqIter_Type}. |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4408 \versionadded{2.2} |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4409 \end{cfuncdesc} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4410 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4411 \begin{cfuncdesc}{PyObject*}{PySeqIter_New}{PyObject *seq} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4412 Return an iterator that works with a general sequence object, |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4413 \var{seq}. The iteration ends when the sequence raises |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4414 \exception{IndexError} for the subscripting operation. |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4415 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4416 \end{cfuncdesc} |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4417 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4418 \begin{cvardesc}{PyTypeObject}{PyCallIter_Type} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4419 Type object for iterator objects returned by |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4420 \cfunction{PyCallIter_New()} and the two-argument form of the |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4421 \function{iter()} built-in function. |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4422 \versionadded{2.2} |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4423 \end{cvardesc} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4424 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4425 \begin{cfuncdesc}{int}{PyCallIter_Check}{op} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4426 Return true if the type of \var{op} is \cdata{PyCallIter_Type}. |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4427 \versionadded{2.2} |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4428 \end{cfuncdesc} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4429 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4430 \begin{cfuncdesc}{PyObject*}{PyCallIter_New}{PyObject *callable, |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4431 PyObject *sentinel} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4432 Return a new iterator. The first parameter, \var{callable}, can be |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4433 any Python callable object that can be called with no parameters; |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4434 each call to it should return the next item in the iteration. When |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4435 \var{callable} returns a value equal to \var{sentinel}, the |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4436 iteration will be terminated. |
|
20055
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4437 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4438 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4439 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4440 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4441 \subsection{Descriptor Objects \label{descriptor-objects}} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4442 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4443 \begin{cvardesc}{PyTypeObject}{PyProperty_Type} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4444 The type object for a descriptor. |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4445 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4446 \end{cvardesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4447 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4448 \begin{cfuncdesc}{PyObject*}{PyDescr_NewGetSet}{PyTypeObject *type, |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4449 PyGetSetDef *getset} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4450 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4451 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4452 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4453 \begin{cfuncdesc}{PyObject*}{PyDescr_NewMember}{PyTypeObject *type, |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4454 PyMemberDef *meth} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4455 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4456 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4457 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4458 \begin{cfuncdesc}{PyObject*}{PyDescr_NewMethod}{PyTypeObject *type, |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4459 PyMethodDef *meth} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4460 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4461 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4462 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4463 \begin{cfuncdesc}{PyObject*}{PyDescr_NewWrapper}{PyTypeObject *type, |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4464 struct wrapperbase *wrapper, |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4465 void *wrapped} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4466 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4467 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4468 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4469 \begin{cfuncdesc}{int}{PyDescr_IsData}{PyObject *descr} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4470 Returns true if the descriptor objects \var{descr} describes a data |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4471 attribute, or false if it describes a method. \var{descr} must be a |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4472 descriptor object; there is no error checking. |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4473 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4474 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4475 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4476 \begin{cfuncdesc}{PyObject*}{PyWrapper_New}{PyObject *, PyObject *} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4477 \versionadded{2.2} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4478 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4479 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4480 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4481 \subsection{Slice Objects \label{slice-objects}} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4482 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4483 \begin{cvardesc}{PyTypeObject}{PySlice_Type} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4484 The type object for slice objects. This is the same as |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4485 \code{types.SliceType}. |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4486 \withsubitem{(in module types)}{\ttindex{SliceType}} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4487 \end{cvardesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4488 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4489 \begin{cfuncdesc}{int}{PySlice_Check}{PyObject *ob} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4490 Returns true if \var{ob} is a slice object; \var{ob} must not be |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4491 \NULL. |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4492 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4493 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4494 \begin{cfuncdesc}{PyObject*}{PySlice_New}{PyObject *start, PyObject *stop, |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4495 PyObject *step} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4496 Return a new slice object with the given values. The \var{start}, |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4497 \var{stop}, and \var{step} parameters are used as the values of the |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4498 slice object attributes of the same names. Any of the values may be |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4499 \NULL, in which case the \code{None} will be used for the |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4500 corresponding attribute. Returns \NULL{} if the new object could |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4501 not be allocated. |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4502 \end{cfuncdesc} |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4503 |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4504 \begin{cfuncdesc}{int}{PySlice_GetIndices}{PySliceObject *slice, int length, |
|
88a03ea57714
Add more signature information and some descriptions for the new APIs
Fred Drake <fdrake@acm.org>
parents:
20041
diff
changeset
|
4505 int *start, int *stop, int *step} |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4506 \end{cfuncdesc} |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4507 |
|
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4508 |
|
20286
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4509 \subsection{Weak Reference Objects \label{weakref-objects}} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4510 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4511 Python supports \emph{weak references} as first-class objects. There |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4512 are two specific object types which directly implement weak |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4513 references. The first is a simple reference object, and the second |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4514 acts as a proxy for the original object as much as it can. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4515 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4516 \begin{cfuncdesc}{int}{PyWeakref_Check}{ob} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4517 Return true if \var{ob} is either a reference or proxy object. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4518 \versionadded{2.2} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4519 \end{cfuncdesc} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4520 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4521 \begin{cfuncdesc}{int}{PyWeakref_CheckRef}{ob} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4522 Return true if \var{ob} is a reference object. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4523 \versionadded{2.2} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4524 \end{cfuncdesc} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4525 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4526 \begin{cfuncdesc}{int}{PyWeakref_CheckProxy}{ob} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4527 Return true if \var{ob} is a proxy object. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4528 \versionadded{2.2} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4529 \end{cfuncdesc} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4530 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4531 \begin{cfuncdesc}{PyObject*}{PyWeakref_NewRef}{PyObject *ob, |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4532 PyObject *callback} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4533 Return a weak reference object for the object \var{ob}. This will |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4534 always return a new reference, but is not guaranteed to create a new |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4535 object; an existing reference object may be returned. The second |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4536 parameter, \var{callback}, can be a callable object that receives |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4537 notification when \var{ob} is garbage collected; it should accept a |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4538 single paramter, which will be the weak reference object itself. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4539 \var{callback} may also be \code{None} or \NULL. If \var{ob} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4540 is not a weakly-referencable object, or if \var{callback} is not |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4541 callable, \code{None}, or \NULL, this will return \NULL{} and |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4542 raise \exception{TypeError}. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4543 \versionadded{2.2} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4544 \end{cfuncdesc} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4545 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4546 \begin{cfuncdesc}{PyObject*}{PyWeakref_NewProxy}{PyObject *ob, |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4547 PyObject *callback} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4548 Return a weak reference proxy object for the object \var{ob}. This |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4549 will always return a new reference, but is not guaranteed to create |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4550 a new object; an existing proxy object may be returned. The second |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4551 parameter, \var{callback}, can be a callable object that receives |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4552 notification when \var{ob} is garbage collected; it should accept a |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4553 single paramter, which will be the weak reference object itself. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4554 \var{callback} may also be \code{None} or \NULL. If \var{ob} is not |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4555 a weakly-referencable object, or if \var{callback} is not callable, |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4556 \code{None}, or \NULL, this will return \NULL{} and raise |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4557 \exception{TypeError}. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4558 \versionadded{2.2} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4559 \end{cfuncdesc} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4560 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4561 \begin{cfuncdesc}{PyObject*}{PyWeakref_GetObject}{PyObject *ref} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4562 Returns the referenced object from a weak reference, \var{ref}. If |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4563 the referent is no longer live, returns \NULL. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4564 \versionadded{2.2} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4565 \end{cfuncdesc} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4566 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4567 \begin{cfuncdesc}{PyObject*}{PyWeakref_GET_OBJECT}{PyObject *ref} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4568 Similar to \cfunction{PyWeakref_GetObject()}, but implemented as a |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4569 macro that does no error checking. |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4570 \versionadded{2.2} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4571 \end{cfuncdesc} |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4572 |
|
c853d246f3c8
Add documentation for the public API for weak reference objects.
Fred Drake <fdrake@acm.org>
parents:
20237
diff
changeset
|
4573 |
| 10163 | 4574 \subsection{CObjects \label{cObjects}} |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4575 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4576 \obindex{CObject} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4577 Refer to \emph{Extending and Embedding the Python Interpreter}, |
|
20041
cd72b64aec97
Added API information for the PyCallIter_*() and PySeqIter_*() functions.
Fred Drake <fdrake@acm.org>
parents:
20009
diff
changeset
|
4578 section 1.12 (``Providing a C API for an Extension Module), for more |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4579 information on using these objects. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4580 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4581 |
|
8109
2e49bc89fafa
Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents:
8057
diff
changeset
|
4582 \begin{ctypedesc}{PyCObject} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
4583 This subtype of \ctype{PyObject} represents an opaque value, useful for |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4584 C extension modules who need to pass an opaque value (as a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4585 \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
|
4586 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
|
4587 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
|
4588 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
|
4589 \end{ctypedesc} |
|
2e49bc89fafa
Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents:
8057
diff
changeset
|
4590 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4591 \begin{cfuncdesc}{int}{PyCObject_Check}{PyObject *p} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4592 Returns true if its argument is a \ctype{PyCObject}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4593 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4594 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4595 \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtr}{void* cobj, |
|
15953
8349b4dfc51a
Undoing the whitespace patches which sneaked into the earlier patch.
Marc-André Lemburg <mal@egenix.com>
parents:
15952
diff
changeset
|
4596 void (*destr)(void *)} |
| 12947 | 4597 Creates a \ctype{PyCObject} from the \code{void *}\var{cobj}. The |
|
10851
fcb25335d6ae
PyCObject_FromVoidPtr(): Clarify that the destr function will only be
Fred Drake <fdrake@acm.org>
parents:
10786
diff
changeset
|
4598 \var{destr} function will be called when the object is reclaimed, unless |
|
fcb25335d6ae
PyCObject_FromVoidPtr(): Clarify that the destr function will only be
Fred Drake <fdrake@acm.org>
parents:
10786
diff
changeset
|
4599 it is \NULL. |
|
8109
2e49bc89fafa
Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents:
8057
diff
changeset
|
4600 \end{cfuncdesc} |
|
2e49bc89fafa
Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents:
8057
diff
changeset
|
4601 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4602 \begin{cfuncdesc}{PyObject*}{PyCObject_FromVoidPtrAndDesc}{void* cobj, |
|
15953
8349b4dfc51a
Undoing the whitespace patches which sneaked into the earlier patch.
Marc-André Lemburg <mal@egenix.com>
parents:
15952
diff
changeset
|
4603 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
|
4604 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
|
4605 \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
|
4606 \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
|
4607 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
|
4608 \end{cfuncdesc} |
|
2e49bc89fafa
Filled in some more blanks, with the help of Drew Csillag.
Guido van Rossum <guido@python.org>
parents:
8057
diff
changeset
|
4609 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4610 \begin{cfuncdesc}{void*}{PyCObject_AsVoidPtr}{PyObject* self} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4611 Returns the object \ctype{void *} that the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4612 \ctype{PyCObject} \var{self} was created with. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4613 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4614 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4615 \begin{cfuncdesc}{void*}{PyCObject_GetDesc}{PyObject* self} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4616 Returns the description \ctype{void *} that the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4617 \ctype{PyCObject} \var{self} was created with. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4618 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4619 |
|
7269
682d3e5b267f
Reorganized a bit. No changed content.
Fred Drake <fdrake@acm.org>
parents:
7268
diff
changeset
|
4620 |
| 10163 | 4621 \chapter{Initialization, Finalization, and Threads |
| 4622 \label{initialization}} | |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4623 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4624 \begin{cfuncdesc}{void}{Py_Initialize}{} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4625 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
|
4626 Python, this should be called before using any other Python/C API |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4627 functions; with the exception of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4628 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4629 \cfunction{PyEval_InitThreads()}\ttindex{PyEval_InitThreads()}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4630 \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4631 and \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4632 This initializes the table of loaded modules (\code{sys.modules}), and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4633 \withsubitem{(in module sys)}{\ttindex{modules}\ttindex{path}}creates the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4634 fundamental modules \module{__builtin__}\refbimodindex{__builtin__}, |
|
7310
6095a472f574
Place C typedef for Py_complex after brief description, to be more consistent
Fred Drake <fdrake@acm.org>
parents:
7309
diff
changeset
|
4635 \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
|
4636 \module{sys}\refbimodindex{sys}. It also initializes the module |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4637 search\indexiii{module}{search}{path} path (\code{sys.path}). |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4638 It does not set \code{sys.argv}; use |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4639 \cfunction{PySys_SetArgv()}\ttindex{PySys_SetArgv()} for that. This |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4640 is a no-op when called for a second time (without calling |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4641 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} first). There is no |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4642 return value; it is a fatal error if the initialization fails. |
|
6382
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
4643 \end{cfuncdesc} |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
4644 |
|
16cd39805fd5
Checkpoint. Added docs for the new exception handling APIs and for
Guido van Rossum <guido@python.org>
parents:
6126
diff
changeset
|
4645 \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
|
4646 Return true (nonzero) when the Python interpreter has been |
| 7308 | 4647 initialized, false (zero) if not. After \cfunction{Py_Finalize()} is |
| 4648 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
|
4649 again. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4650 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4651 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4652 \begin{cfuncdesc}{void}{Py_Finalize}{} |
| 7308 | 4653 Undo all initializations made by \cfunction{Py_Initialize()} and |
| 4654 subsequent use of Python/C API functions, and destroy all | |
| 4655 sub-interpreters (see \cfunction{Py_NewInterpreter()} below) that were | |
| 4656 created and not yet destroyed since the last call to | |
| 4657 \cfunction{Py_Initialize()}. Ideally, this frees all memory allocated | |
| 4658 by the Python interpreter. This is a no-op when called for a second | |
| 4659 time (without calling \cfunction{Py_Initialize()} again first). There | |
| 4660 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
|
4661 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4662 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
|
4663 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
|
4664 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
|
4665 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
|
4666 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
|
4667 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
|
4668 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
|
4669 |
| 7308 | 4670 \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
|
4671 modules is done in random order; this may cause destructors |
| 7308 | 4672 (\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
|
4673 (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
|
4674 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
|
4675 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
|
4676 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
|
4677 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
|
4678 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
|
4679 routine is called more than once; this can happen if an applcation |
| 7308 | 4680 calls \cfunction{Py_Initialize()} and \cfunction{Py_Finalize()} more |
| 4681 than once. | |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4682 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4683 |
| 7782 | 4684 \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
|
4685 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
|
4686 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
|
4687 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
|
4688 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
|
4689 \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
|
4690 \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
|
4691 \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
|
4692 (\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
|
4693 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
|
4694 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
|
4695 \code{sys.stdout} and \code{sys.stderr} (however these refer to the |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4696 same underlying \ctype{FILE} structures in the C library). |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4697 \withsubitem{(in module sys)}{ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4698 \ttindex{stdout}\ttindex{stderr}\ttindex{stdin}} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4699 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4700 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
|
4701 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
|
4702 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
|
4703 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
|
4704 \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
|
4705 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
|
4706 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
|
4707 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
|
4708 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
|
4709 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
|
4710 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4711 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
|
4712 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
|
4713 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
|
4714 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
|
4715 (sub-)interpreter, a new module is initialized and filled with the |
| 7308 | 4716 contents of this copy; the extension's \code{init} function is not |
| 4717 called. Note that this is different from what happens when an | |
| 4718 extension is imported after the interpreter has been completely | |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4719 re-initialized by calling |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4720 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4721 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}; in that case, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4722 the extension's \code{init\var{module}} function \emph{is} called |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4723 again. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4724 |
| 7308 | 4725 \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
|
4726 interpreter) are part of the same process, the insulation between them |
| 7308 | 4727 isn't perfect --- for example, using low-level file operations like |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4728 \withsubitem{(in module os)}{\ttindex{close()}} |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
4729 \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
|
4730 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
|
4731 (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
|
4732 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
|
4733 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
|
4734 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
|
4735 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
|
4736 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
|
4737 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
|
4738 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
|
4739 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
|
4740 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
|
4741 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4742 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4743 \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
|
4744 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
|
4745 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
|
4746 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
|
4747 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
|
4748 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
|
4749 before calling this function and is still held when it returns.) |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4750 \cfunction{Py_Finalize()}\ttindex{Py_Finalize()} will destroy all |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4751 sub-interpreters that haven't been explicitly destroyed at that point. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4752 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4753 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4754 \begin{cfuncdesc}{void}{Py_SetProgramName}{char *name} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4755 This function should be called before |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4756 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()} is called |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4757 for the first time, if it is called at all. It tells the interpreter |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4758 the value of the \code{argv[0]} argument to the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4759 \cfunction{main()}\ttindex{main()} function of the program. This is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4760 used by \cfunction{Py_GetPath()}\ttindex{Py_GetPath()} and some other |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4761 functions below to find the Python run-time libraries relative to the |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4762 interpreter executable. The default value is \code{'python'}. The |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4763 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
|
4764 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
|
4765 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
|
4766 the contents of this storage. |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4767 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4768 |
| 7782 | 4769 \begin{cfuncdesc}{char*}{Py_GetProgramName}{} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4770 Return the program name set with |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4771 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()}, or the |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4772 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
|
4773 should not modify its value. |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4774 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4775 |
| 7782 | 4776 \begin{cfuncdesc}{char*}{Py_GetPrefix}{} |
| 7308 | 4777 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
|
4778 is derived through a number of complicated rules from the program name |
| 7308 | 4779 set with \cfunction{Py_SetProgramName()} and some environment variables; |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4780 for example, if the program name is \code{'/usr/local/bin/python'}, |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4781 the prefix is \code{'/usr/local'}. The returned string points into |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4782 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
|
4783 corresponds to the \makevar{prefix} variable in the top-level |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4784 \file{Makefile} and the \longprogramopt{prefix} argument to the |
| 7308 | 4785 \program{configure} script at build time. The value is available to |
| 7081 | 4786 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
|
4787 also the next function. |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4788 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4789 |
| 7782 | 4790 \begin{cfuncdesc}{char*}{Py_GetExecPrefix}{} |
| 7308 | 4791 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
|
4792 files. This is derived through a number of complicated rules from the |
| 7308 | 4793 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
|
4794 variables; for example, if the program name is |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4795 \code{'/usr/local/bin/python'}, the exec-prefix is |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4796 \code{'/usr/local'}. The returned string points into static storage; |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4797 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
|
4798 \makevar{exec_prefix} variable in the top-level \file{Makefile} and the |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4799 \longprogramopt{exec-prefix} argument to the |
|
11453
a05a05602902
Missed a couple of program options that had been marked by \code.
Fred Drake <fdrake@acm.org>
parents:
11451
diff
changeset
|
4800 \program{configure} script at build time. The value is available to |
|
a05a05602902
Missed a couple of program options that had been marked by \code.
Fred Drake <fdrake@acm.org>
parents:
11451
diff
changeset
|
4801 Python code as \code{sys.exec_prefix}. It is only useful on \UNIX{}. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4802 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4803 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
|
4804 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
|
4805 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
|
4806 platform dependent files may be installed in the |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4807 \file{/usr/local/plat} subtree while platform independent may be |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4808 installed in \file{/usr/local}. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4809 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4810 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
|
4811 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
|
4812 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
|
4813 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
|
4814 Linux are yet another platform. Different major revisions of the same |
| 7081 | 4815 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
|
4816 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
|
4817 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
|
4818 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
|
4819 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
|
4820 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
|
4821 |
| 7308 | 4822 System administrators will know how to configure the \program{mount} or |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4823 \program{automount} programs to share \file{/usr/local} between platforms |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4824 while having \file{/usr/local/plat} be a different filesystem for each |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4825 platform. |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4826 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4827 |
| 7782 | 4828 \begin{cfuncdesc}{char*}{Py_GetProgramFullPath}{} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4829 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
|
4830 computed as a side-effect of deriving the default module search path |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4831 from the program name (set by |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4832 \cfunction{Py_SetProgramName()}\ttindex{Py_SetProgramName()} above). |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4833 The returned string points into static storage; the caller should not |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4834 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
|
4835 \code{sys.executable}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4836 \withsubitem{(in module sys)}{\ttindex{executable}} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4837 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4838 |
| 7782 | 4839 \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
|
4840 \indexiii{module}{search}{path} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4841 Return the default module search path; this is computed from the |
| 7308 | 4842 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
|
4843 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
|
4844 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
|
4845 The delimiter character is \character{:} on \UNIX{}, \character{;} on |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4846 DOS/Windows, and \character{\e n} (the \ASCII{} newline character) on |
| 7271 | 4847 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
|
4848 should not modify its value. The value is available to Python code |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4849 as the list \code{sys.path}\withsubitem{(in module sys)}{\ttindex{path}}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4850 which may be modified to change the future search path for loaded |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4851 modules. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4852 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4853 % XXX should give the exact rules |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4854 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4855 |
| 7782 | 4856 \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
|
4857 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
|
4858 looks something like |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4859 |
|
6074
5e5e54a6dba6
Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents:
6041
diff
changeset
|
4860 \begin{verbatim} |
| 7308 | 4861 "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
|
4862 \end{verbatim} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4863 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4864 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
|
4865 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
|
4866 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
|
4867 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
|
4868 Python code as the list \code{sys.version}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4869 \withsubitem{(in module sys)}{\ttindex{version}} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4870 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4871 |
| 7782 | 4872 \begin{cfuncdesc}{const char*}{Py_GetPlatform}{} |
| 7081 | 4873 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
|
4874 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
|
4875 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
|
4876 for Solaris 2.x, which is also known as SunOS 5.x, the value is |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4877 \code{'sunos5'}. On Macintosh, it is \code{'mac'}. On Windows, it |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4878 is \code{'win'}. The returned string points into static storage; |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4879 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
|
4880 Python code as \code{sys.platform}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4881 \withsubitem{(in module sys)}{\ttindex{platform}} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4882 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4883 |
| 7782 | 4884 \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
|
4885 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
|
4886 for example |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4887 |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
4888 \code{'Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam'} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4889 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4890 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
|
4891 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
|
4892 \code{sys.copyright}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4893 \withsubitem{(in module sys)}{\ttindex{copyright}} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4894 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4895 |
| 7782 | 4896 \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
|
4897 Return an indication of the compiler used to build the current Python |
| 7308 | 4898 version, in square brackets, for example: |
| 4899 | |
| 4900 \begin{verbatim} | |
| 4901 "[GCC 2.7.2.2]" | |
| 4902 \end{verbatim} | |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4903 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4904 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
|
4905 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
|
4906 the variable \code{sys.version}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4907 \withsubitem{(in module sys)}{\ttindex{version}} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4908 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4909 |
| 7782 | 4910 \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
|
4911 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
|
4912 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
|
4913 |
|
6074
5e5e54a6dba6
Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents:
6041
diff
changeset
|
4914 \begin{verbatim} |
|
5e5e54a6dba6
Fixes to make it pass latex without complaints.
Guido van Rossum <guido@python.org>
parents:
6041
diff
changeset
|
4915 "#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
|
4916 \end{verbatim} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4917 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4918 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
|
4919 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
|
4920 the variable \code{sys.version}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4921 \withsubitem{(in module sys)}{\ttindex{version}} |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4922 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4923 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4924 \begin{cfuncdesc}{int}{PySys_SetArgv}{int argc, char **argv} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4925 Set \code{sys.argv} based on \var{argc} and \var{argv}. These |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4926 parameters are similar to those passed to the program's |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4927 \cfunction{main()}\ttindex{main()} function with the difference that |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4928 the first entry should refer to the script file to be executed rather |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4929 than the executable hosting the Python interpreter. If there isn't a |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4930 script that will be run, the first entry in \var{argv} can be an empty |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4931 string. If this function fails to initialize \code{sys.argv}, a fatal |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4932 condition is signalled using |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4933 \cfunction{Py_FatalError()}\ttindex{Py_FatalError()}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4934 \withsubitem{(in module sys)}{\ttindex{argv}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4935 % XXX impl. doesn't seem consistent in allowing 0/NULL for the params; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4936 % check w/ Guido. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4937 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4938 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4939 % 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
|
4940 |
| 10163 | 4941 \section{Thread State and the Global Interpreter Lock |
| 4942 \label{threads}} | |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
4943 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4944 \index{global interpreter lock} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4945 \index{interpreter lock} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4946 \index{lock, interpreter} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4947 |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4948 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
|
4949 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
|
4950 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
|
4951 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
|
4952 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
|
4953 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
|
4954 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
|
4955 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4956 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
|
4957 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
|
4958 API functions. In order to support multi-threaded Python programs, |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4959 the interpreter regularly releases and reacquires the lock --- by |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4960 default, every ten bytecode instructions (this can be changed with |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4961 \withsubitem{(in module sys)}{\ttindex{setcheckinterval()}} |
| 7308 | 4962 \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
|
4963 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
|
4964 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
|
4965 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
|
4966 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4967 The Python interpreter needs to keep some bookkeeping information |
| 7308 | 4968 separate per thread --- for this it uses a data structure called |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4969 \ctype{PyThreadState}\ttindex{PyThreadState}. This is new in Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4970 1.5; in earlier versions, such state was stored in global variables, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4971 and switching threads could cause problems. In particular, exception |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4972 handling is now thread safe, when the application uses |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4973 \withsubitem{(in module sys)}{\ttindex{exc_info()}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4974 \function{sys.exc_info()} to access the exception last raised in the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4975 current thread. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4976 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4977 There's one global variable left, however: the pointer to the current |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4978 \ctype{PyThreadState}\ttindex{PyThreadState} structure. While most |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4979 thread packages have a way to store ``per-thread global data,'' |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4980 Python's internal platform independent thread abstraction doesn't |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4981 support this yet. Therefore, the current thread state must be |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
4982 manipulated explicitly. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4983 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4984 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
|
4985 interpreter lock has the following simple structure: |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4986 |
|
6417
4491f84ac223
Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents:
6390
diff
changeset
|
4987 \begin{verbatim} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4988 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
|
4989 Release the interpreter lock. |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4990 ...Do some blocking I/O operation... |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4991 Reacquire the interpreter lock. |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4992 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
|
4993 \end{verbatim} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4994 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4995 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
|
4996 |
|
6417
4491f84ac223
Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents:
6390
diff
changeset
|
4997 \begin{verbatim} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4998 Py_BEGIN_ALLOW_THREADS |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
4999 ...Do some blocking I/O operation... |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5000 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
|
5001 \end{verbatim} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5002 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5003 The \code{Py_BEGIN_ALLOW_THREADS}\ttindex{Py_BEGIN_ALLOW_THREADS} macro |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5004 opens a new block and declares a hidden local variable; the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5005 \code{Py_END_ALLOW_THREADS}\ttindex{Py_END_ALLOW_THREADS} macro closes |
| 7308 | 5006 the block. Another advantage of using these two macros is that when |
| 5007 Python is compiled without thread support, they are defined empty, | |
| 5008 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
|
5009 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5010 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
|
5011 following code: |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5012 |
|
6417
4491f84ac223
Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents:
6390
diff
changeset
|
5013 \begin{verbatim} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5014 PyThreadState *_save; |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5015 |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5016 _save = PyEval_SaveThread(); |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5017 ...Do some blocking I/O operation... |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5018 PyEval_RestoreThread(_save); |
|
6417
4491f84ac223
Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents:
6390
diff
changeset
|
5019 \end{verbatim} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5020 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5021 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
|
5022 as follows: |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5023 |
|
6417
4491f84ac223
Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents:
6390
diff
changeset
|
5024 \begin{verbatim} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5025 PyThreadState *_save; |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5026 |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5027 _save = PyThreadState_Swap(NULL); |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5028 PyEval_ReleaseLock(); |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5029 ...Do some blocking I/O operation... |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5030 PyEval_AcquireLock(); |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5031 PyThreadState_Swap(_save); |
|
6417
4491f84ac223
Change title to {Python/C API Reference Manual}; remove \bcode \ecode
Guido van Rossum <guido@python.org>
parents:
6390
diff
changeset
|
5032 \end{verbatim} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5033 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5034 There are some subtle differences; in particular, |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5035 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()} saves |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5036 and restores the value of the global variable |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5037 \cdata{errno}\ttindex{errno}, since the lock manipulation does not |
|
8120
068fea15cbcd
Convert recent additions to use new, "logical" markup.
Fred Drake <fdrake@acm.org>
parents:
8109
diff
changeset
|
5038 guarantee that \cdata{errno} is left alone. Also, when thread support |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5039 is disabled, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5040 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} and |
| 7308 | 5041 \cfunction{PyEval_RestoreThread()} don't manipulate the lock; in this |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5042 case, \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5043 \cfunction{PyEval_AcquireLock()}\ttindex{PyEval_AcquireLock()} are not |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5044 available. This is done so that dynamically loaded extensions |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5045 compiled with thread support enabled can be loaded by an interpreter |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5046 that was compiled with disabled thread support. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5047 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5048 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
|
5049 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
|
5050 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
|
5051 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
|
5052 lock and store its own thread state in the global variable). |
| 14926 | 5053 Conversely, when acquiring the lock and restoring the thread state, |
| 5054 the lock must be acquired before storing the thread state pointer. | |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5055 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5056 Why am I going on with so much detail about this? Because when |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5057 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
|
5058 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
|
5059 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
|
5060 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
|
5061 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
|
5062 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
|
5063 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
|
5064 structure. |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5065 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5066 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
|
5067 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
|
5068 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
|
5069 interpreter, for example the module administration |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5070 (\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
|
5071 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
|
5072 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
|
5073 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
|
5074 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
|
5075 thread after Python is initialized). |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5076 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5077 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5078 \begin{ctypedesc}{PyInterpreterState} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5079 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
|
5080 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
|
5081 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
|
5082 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
|
5083 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5084 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
|
5085 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
|
5086 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
|
5087 regardless of to which interpreter they belong. |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5088 \end{ctypedesc} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5089 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5090 \begin{ctypedesc}{PyThreadState} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5091 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
|
5092 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
|
5093 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
|
5094 \end{ctypedesc} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5095 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5096 \begin{cfuncdesc}{void}{PyEval_InitThreads}{} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5097 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
|
5098 called in the main thread before creating a second thread or engaging |
| 7308 | 5099 in any other thread operations such as |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5100 \cfunction{PyEval_ReleaseLock()}\ttindex{PyEval_ReleaseLock()} or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5101 \code{PyEval_ReleaseThread(\var{tstate})}\ttindex{PyEval_ReleaseThread()}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5102 It is not needed before calling |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5103 \cfunction{PyEval_SaveThread()}\ttindex{PyEval_SaveThread()} or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5104 \cfunction{PyEval_RestoreThread()}\ttindex{PyEval_RestoreThread()}. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5105 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5106 This is a no-op when called for a second time. It is safe to call |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5107 this function before calling |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5108 \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5109 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5110 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
|
5111 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
|
5112 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
|
5113 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
|
5114 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
|
5115 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
|
5116 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
|
5117 \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
|
5118 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
|
5119 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
|
5120 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
|
5121 has acquired it. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5122 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5123 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
|
5124 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
|
5125 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5126 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
|
5127 compile time. |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5128 \end{cfuncdesc} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5129 |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5130 \begin{cfuncdesc}{void}{PyEval_AcquireLock}{} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5131 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
|
5132 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
|
5133 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
|
5134 compile time. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5135 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5136 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5137 \begin{cfuncdesc}{void}{PyEval_ReleaseLock}{} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5138 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
|
5139 earlier. This function is not available when thread support is |
| 7308 | 5140 disabled at compile time. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5141 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5142 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5143 \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
|
5144 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
|
5145 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
|
5146 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
|
5147 deadlock ensues. This function is not available when thread support |
| 7308 | 5148 is disabled at compile time. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5149 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5150 |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5151 \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
|
5152 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
|
5153 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
|
5154 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
|
5155 be \NULL{}, is only used to check that it represents the current |
| 7308 | 5156 thread state --- if it isn't, a fatal error is reported. This |
| 5157 function is not available when thread support is disabled at compile | |
| 5158 time. | |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5159 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5160 |
| 7782 | 5161 \begin{cfuncdesc}{PyThreadState*}{PyEval_SaveThread}{} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5162 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
|
5163 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
|
5164 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
|
5165 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
|
5166 (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
|
5167 compile time.) |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5168 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5169 |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5170 \begin{cfuncdesc}{void}{PyEval_RestoreThread}{PyThreadState *tstate} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5171 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
|
5172 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
|
5173 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
|
5174 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
|
5175 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
|
5176 time.) |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5177 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5178 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5179 The following macros are normally used without a trailing semicolon; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5180 look for example usage in the Python source distribution. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5181 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5182 \begin{csimplemacrodesc}{Py_BEGIN_ALLOW_THREADS} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5183 This macro expands to |
| 7308 | 5184 \samp{\{ PyThreadState *_save; _save = PyEval_SaveThread();}. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5185 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
|
5186 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
|
5187 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
|
5188 disabled at compile time. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5189 \end{csimplemacrodesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5190 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5191 \begin{csimplemacrodesc}{Py_END_ALLOW_THREADS} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5192 This macro expands to |
| 7308 | 5193 \samp{PyEval_RestoreThread(_save); \}}. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5194 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
|
5195 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
|
5196 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
|
5197 disabled at compile time. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5198 \end{csimplemacrodesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5199 |
|
18438
05c49346b68b
Fix for SF bug #436525, reported by Greg Kochanski:
Thomas Wouters <thomas@python.org>
parents:
18192
diff
changeset
|
5200 \begin{csimplemacrodesc}{Py_BLOCK_THREADS} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5201 This macro expands to \samp{PyEval_RestoreThread(_save);}: it |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5202 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
|
5203 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
|
5204 time. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5205 \end{csimplemacrodesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5206 |
|
18438
05c49346b68b
Fix for SF bug #436525, reported by Greg Kochanski:
Thomas Wouters <thomas@python.org>
parents:
18192
diff
changeset
|
5207 \begin{csimplemacrodesc}{Py_UNBLOCK_THREADS} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5208 This macro expands to \samp{_save = PyEval_SaveThread();}: it is |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5209 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
|
5210 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
|
5211 disabled at compile time. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5212 \end{csimplemacrodesc} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5213 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5214 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
|
5215 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
|
5216 interpreter lock has been created. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5217 |
| 7782 | 5218 \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_New}{} |
|
8881
febca6b1827d
Clarify that the Python interpreter lock need *not* be held by
Guido van Rossum <guido@python.org>
parents:
8782
diff
changeset
|
5219 Create a new interpreter state object. The interpreter lock need not |
|
febca6b1827d
Clarify that the Python interpreter lock need *not* be held by
Guido van Rossum <guido@python.org>
parents:
8782
diff
changeset
|
5220 be held, but may be held if it is necessary to serialize calls to this |
|
febca6b1827d
Clarify that the Python interpreter lock need *not* be held by
Guido van Rossum <guido@python.org>
parents:
8782
diff
changeset
|
5221 function. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5222 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5223 |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5224 \begin{cfuncdesc}{void}{PyInterpreterState_Clear}{PyInterpreterState *interp} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5225 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
|
5226 lock must be held. |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5227 \end{cfuncdesc} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5228 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5229 \begin{cfuncdesc}{void}{PyInterpreterState_Delete}{PyInterpreterState *interp} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5230 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
|
5231 held. The interpreter state must have been reset with a previous |
| 7308 | 5232 call to \cfunction{PyInterpreterState_Clear()}. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5233 \end{cfuncdesc} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5234 |
| 7782 | 5235 \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
|
5236 Create a new thread state object belonging to the given interpreter |
|
8881
febca6b1827d
Clarify that the Python interpreter lock need *not* be held by
Guido van Rossum <guido@python.org>
parents:
8782
diff
changeset
|
5237 object. The interpreter lock need not be held, but may be held if it |
|
febca6b1827d
Clarify that the Python interpreter lock need *not* be held by
Guido van Rossum <guido@python.org>
parents:
8782
diff
changeset
|
5238 is necessary to serialize calls to this function. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5239 \end{cfuncdesc} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5240 |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5241 \begin{cfuncdesc}{void}{PyThreadState_Clear}{PyThreadState *tstate} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5242 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
|
5243 must be held. |
|
6041
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5244 \end{cfuncdesc} |
|
a9e1ea80ea3f
Added more stuff on initialization (still rudimentary)
Guido van Rossum <guido@python.org>
parents:
6040
diff
changeset
|
5245 |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5246 \begin{cfuncdesc}{void}{PyThreadState_Delete}{PyThreadState *tstate} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5247 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
|
5248 held. The thread state must have been reset with a previous |
| 7308 | 5249 call to \cfunction{PyThreadState_Clear()}. |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5250 \end{cfuncdesc} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5251 |
| 7782 | 5252 \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Get}{} |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5253 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
|
5254 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
|
5255 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
|
5256 \end{cfuncdesc} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5257 |
| 7782 | 5258 \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
|
5259 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
|
5260 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
|
5261 must be held. |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5262 \end{cfuncdesc} |
|
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5263 |
|
17877
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
5264 \begin{cfuncdesc}{PyObject*}{PyThreadState_GetDict}{} |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
5265 Return a dictionary in which extensions can store thread-specific |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
5266 state information. Each extension should use a unique key to use to |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
5267 store state in the dictionary. If this function returns \NULL, an |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
5268 exception has been raised and the caller should allow it to |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
5269 propogate. |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
5270 \end{cfuncdesc} |
|
13bdb5b207d2
Add documentation for Py_Main() and PyThreadState_GetDict().
Fred Drake <fdrake@acm.org>
parents:
17875
diff
changeset
|
5271 |
|
6390
a2df3c9e5f43
Done with tread state descriptions. Sigh!
Guido van Rossum <guido@python.org>
parents:
6382
diff
changeset
|
5272 |
|
18671
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5273 \section{Profiling and Tracing \label{profiling}} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5274 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5275 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5276 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5277 The Python interpreter provides some low-level support for attaching |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5278 profiling and execution tracing facilities. These are used for |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5279 profiling, debugging, and coverage analysis tools. |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5280 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5281 Starting with Python 2.2, the implementation of this facility was |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5282 substantially revised, and an interface from C was added. This C |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5283 interface allows the profiling or tracing code to avoid the overhead |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5284 of calling through Python-level callable objects, making a direct C |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5285 function call instead. The essential attributes of the facility have |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5286 not changed; the interface allows trace functions to be installed |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5287 per-thread, and the basic events reported to the trace function are |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5288 the same as had been reported to the Python-level trace functions in |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5289 previous versions. |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5290 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5291 \begin{ctypedesc}[Py_tracefunc]{int (*Py_tracefunc)(PyObject *obj, |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5292 PyFrameObject *frame, int what, |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5293 PyObject *arg)} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5294 The type of the trace function registered using |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5295 \cfunction{PyEval_SetProfile()} and \cfunction{PyEval_SetTrace()}. |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5296 The first parameter is the object passed to the registration |
|
20237
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5297 function as \var{obj}, \var{frame} is the frame object to which the |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5298 event pertains, \var{what} is one of the constants |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5299 \constant{PyTrace_CALL}, \constant{PyTrace_EXCEPT}, |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5300 \constant{PyTrace_LINE} or \constant{PyTrace_RETURN}, and \var{arg} |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5301 depends on the value of \var{what}: |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5302 |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5303 \begin{tableii}{l|l}{constant}{Value of \var{what}}{Meaning of \var{arg}} |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5304 \lineii{PyTrace_CALL}{Always \NULL.} |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5305 \lineii{PyTrace_EXCEPT}{Exception information as returned by |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5306 \function{sys.exc_info()}.} |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5307 \lineii{PyTrace_LINE}{Always \NULL.} |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5308 \lineii{PyTrace_RETURN}{Value being returned to the caller.} |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5309 \end{tableii} |
|
18671
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5310 \end{ctypedesc} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5311 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5312 \begin{cvardesc}{int}{PyTrace_CALL} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5313 The value of the \var{what} parameter to a \ctype{Py_tracefunc} |
|
20237
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5314 function when a new call to a function or method is being reported, |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5315 or a new entry into a generator. Note that the creation of the |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5316 iterator for a generator function is not reported as there is no |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5317 control transfer to the Python bytecode in the corresponding frame. |
|
18671
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5318 \end{cvardesc} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5319 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5320 \begin{cvardesc}{int}{PyTrace_EXCEPT} |
|
20237
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5321 The value of the \var{what} parameter to a \ctype{Py_tracefunc} |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5322 function when an exception has been raised by Python code as the |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5323 result of an operation. The operation may have explictly intended |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5324 to raise the operation (as with a \keyword{raise} statement), or may |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5325 have triggered an exception in the runtime as a result of the |
|
d1671ddeace0
Expand the documentation of the low-level tracing/profiling interface.
Fred Drake <fdrake@acm.org>
parents:
20111
diff
changeset
|
5326 specific operation. |
|
18671
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5327 \end{cvardesc} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5328 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5329 \begin{cvardesc}{int}{PyTrace_LINE} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5330 The value passed as the \var{what} parameter to a trace function |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5331 (but not a profiling function) when a line-number event is being |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5332 reported. |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5333 \end{cvardesc} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5334 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5335 \begin{cvardesc}{int}{PyTrace_RETURN} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5336 The value for the \var{what} parameter to \ctype{Py_tracefunc} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5337 functions when a call is returning without propogating an exception. |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5338 \end{cvardesc} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5339 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5340 \begin{cfuncdesc}{void}{PyEval_SetProfile}{Py_tracefunc func, PyObject *obj} |
|
18944
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5341 Set the profiler function to \var{func}. The \var{obj} parameter is |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5342 passed to the function as its first parameter, and may be any Python |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5343 object, or \NULL. If the profile function needs to maintain state, |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5344 using a different value for \var{obj} for each thread provides a |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5345 convenient and thread-safe place to store it. The profile function |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5346 is called for all monitored events except the line-number events. |
|
18671
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5347 \end{cfuncdesc} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5348 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5349 \begin{cfuncdesc}{void}{PyEval_SetTrace}{Py_tracefunc func, PyObject *obj} |
|
18944
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5350 Set the the tracing function to \var{func}. This is similar to |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5351 \cfunction{PyEval_SetProfile()}, except the tracing function does |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5352 receive line-number events. |
|
18671
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5353 \end{cfuncdesc} |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5354 |
|
38206f29b0fc
Adding what's done of the documentation for the new profiling &
Fred Drake <fdrake@acm.org>
parents:
18576
diff
changeset
|
5355 |
|
19076
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5356 \section{Advanced Debugger Support \label{advanced-debugging}} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5357 \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5358 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5359 These functions are only intended to be used by advanced debugging |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5360 tools. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5361 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5362 \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Head}{} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5363 Return the interpreter state object at the head of the list of all |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5364 such objects. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5365 \versionadded{2.2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5366 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5367 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5368 \begin{cfuncdesc}{PyInterpreterState*}{PyInterpreterState_Next}{PyInterpreterState *interp} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5369 Return the next interpreter state object after \var{interp} from the |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5370 list of all such objects. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5371 \versionadded{2.2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5372 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5373 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5374 \begin{cfuncdesc}{PyThreadState *}{PyInterpreterState_ThreadHead}{PyInterpreterState *interp} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5375 Return the a pointer to the first \ctype{PyThreadState} object in the |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5376 list of threads associated with the interpreter \var{interp}. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5377 \versionadded{2.2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5378 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5379 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5380 \begin{cfuncdesc}{PyThreadState*}{PyThreadState_Next}{PyThreadState *tstate} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5381 Return the next thread state object after \var{tstate} from the list |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5382 of all such objects belonging to the same \ctype{PyInterpreterState} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5383 object. |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5384 \versionadded{2.2} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5385 \end{cfuncdesc} |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5386 |
|
f75125ead0a2
Added documentation for PyNumber_*FloorDivide(), PyNumber_*TrueDivide(),
Fred Drake <fdrake@acm.org>
parents:
18944
diff
changeset
|
5387 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5388 \chapter{Memory Management \label{memory}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5389 \sectionauthor{Vladimir Marangozov}{Vladimir.Marangozov@inrialpes.fr} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5390 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5391 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5392 \section{Overview \label{memoryOverview}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5393 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5394 Memory management in Python involves a private heap containing all |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5395 Python objects and data structures. The management of this private |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5396 heap is ensured internally by the \emph{Python memory manager}. The |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5397 Python memory manager has different components which deal with various |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5398 dynamic storage management aspects, like sharing, segmentation, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5399 preallocation or caching. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5400 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5401 At the lowest level, a raw memory allocator ensures that there is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5402 enough room in the private heap for storing all Python-related data |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5403 by interacting with the memory manager of the operating system. On top |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5404 of the raw memory allocator, several object-specific allocators |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5405 operate on the same heap and implement distinct memory management |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5406 policies adapted to the peculiarities of every object type. For |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5407 example, integer objects are managed differently within the heap than |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5408 strings, tuples or dictionaries because integers imply different |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5409 storage requirements and speed/space tradeoffs. The Python memory |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5410 manager thus delegates some of the work to the object-specific |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5411 allocators, but ensures that the latter operate within the bounds of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5412 the private heap. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5413 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5414 It is important to understand that the management of the Python heap |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5415 is performed by the interpreter itself and that the user has no |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5416 control on it, even if she regularly manipulates object pointers to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5417 memory blocks inside that heap. The allocation of heap space for |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5418 Python objects and other internal buffers is performed on demand by |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5419 the Python memory manager through the Python/C API functions listed in |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5420 this document. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5421 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5422 To avoid memory corruption, extension writers should never try to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5423 operate on Python objects with the functions exported by the C |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5424 library: \cfunction{malloc()}\ttindex{malloc()}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5425 \cfunction{calloc()}\ttindex{calloc()}, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5426 \cfunction{realloc()}\ttindex{realloc()} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5427 \cfunction{free()}\ttindex{free()}. This will result in |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5428 mixed calls between the C allocator and the Python memory manager |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5429 with fatal consequences, because they implement different algorithms |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5430 and operate on different heaps. However, one may safely allocate and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5431 release memory blocks with the C library allocator for individual |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5432 purposes, as shown in the following example: |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5433 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5434 \begin{verbatim} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5435 PyObject *res; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5436 char *buf = (char *) malloc(BUFSIZ); /* for I/O */ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5437 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5438 if (buf == NULL) |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5439 return PyErr_NoMemory(); |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5440 ...Do some I/O operation involving buf... |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5441 res = PyString_FromString(buf); |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5442 free(buf); /* malloc'ed */ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5443 return res; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5444 \end{verbatim} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5445 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5446 In this example, the memory request for the I/O buffer is handled by |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5447 the C library allocator. The Python memory manager is involved only |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5448 in the allocation of the string object returned as a result. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5449 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5450 In most situations, however, it is recommended to allocate memory from |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5451 the Python heap specifically because the latter is under control of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5452 the Python memory manager. For example, this is required when the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5453 interpreter is extended with new object types written in C. Another |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5454 reason for using the Python heap is the desire to \emph{inform} the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5455 Python memory manager about the memory needs of the extension module. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5456 Even when the requested memory is used exclusively for internal, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5457 highly-specific purposes, delegating all memory requests to the Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5458 memory manager causes the interpreter to have a more accurate image of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5459 its memory footprint as a whole. Consequently, under certain |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5460 circumstances, the Python memory manager may or may not trigger |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5461 appropriate actions, like garbage collection, memory compaction or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5462 other preventive procedures. Note that by using the C library |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5463 allocator as shown in the previous example, the allocated memory for |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5464 the I/O buffer escapes completely the Python memory manager. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5465 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5466 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5467 \section{Memory Interface \label{memoryInterface}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5468 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5469 The following function sets, modeled after the ANSI C standard, are |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5470 available for allocating and releasing memory from the Python heap: |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5471 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5472 |
|
13920
d057cd543ed9
ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents:
13592
diff
changeset
|
5473 \begin{cfuncdesc}{void*}{PyMem_Malloc}{size_t n} |
|
d057cd543ed9
ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents:
13592
diff
changeset
|
5474 Allocates \var{n} bytes and returns a pointer of type \ctype{void*} to |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5475 the allocated memory, or \NULL{} if the request fails. Requesting zero |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5476 bytes returns a non-\NULL{} pointer. |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5477 The memory will not have been initialized in any way. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5478 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5479 |
|
13920
d057cd543ed9
ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents:
13592
diff
changeset
|
5480 \begin{cfuncdesc}{void*}{PyMem_Realloc}{void *p, size_t n} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5481 Resizes the memory block pointed to by \var{p} to \var{n} bytes. The |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5482 contents will be unchanged to the minimum of the old and the new |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5483 sizes. If \var{p} is \NULL{}, the call is equivalent to |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5484 \cfunction{PyMem_Malloc(\var{n})}; if \var{n} is equal to zero, the |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5485 memory block is resized but is not freed, and the returned pointer is |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5486 non-\NULL{}. Unless \var{p} is \NULL{}, it must have been returned by |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5487 a previous call to \cfunction{PyMem_Malloc()} or |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5488 \cfunction{PyMem_Realloc()}. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5489 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5490 |
|
13920
d057cd543ed9
ANY becomes void, to reflect the requirement for ANSI C.
Fred Drake <fdrake@acm.org>
parents:
13592
diff
changeset
|
5491 \begin{cfuncdesc}{void}{PyMem_Free}{void *p} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5492 Frees the memory block pointed to by \var{p}, which must have been |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5493 returned by a previous call to \cfunction{PyMem_Malloc()} or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5494 \cfunction{PyMem_Realloc()}. Otherwise, or if |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5495 \cfunction{PyMem_Free(p)} has been called before, undefined behaviour |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5496 occurs. If \var{p} is \NULL{}, no operation is performed. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5497 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5498 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5499 The following type-oriented macros are provided for convenience. Note |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5500 that \var{TYPE} refers to any C type. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5501 |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5502 \begin{cfuncdesc}{\var{TYPE}*}{PyMem_New}{TYPE, size_t n} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5503 Same as \cfunction{PyMem_Malloc()}, but allocates \code{(\var{n} * |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5504 sizeof(\var{TYPE}))} bytes of memory. Returns a pointer cast to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5505 \ctype{\var{TYPE}*}. |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5506 The memory will not have been initialized in any way. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5507 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5508 |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5509 \begin{cfuncdesc}{\var{TYPE}*}{PyMem_Resize}{void *p, TYPE, size_t n} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5510 Same as \cfunction{PyMem_Realloc()}, but the memory block is resized |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5511 to \code{(\var{n} * sizeof(\var{TYPE}))} bytes. Returns a pointer |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5512 cast to \ctype{\var{TYPE}*}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5513 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5514 |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5515 \begin{cfuncdesc}{void}{PyMem_Del}{void *p} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5516 Same as \cfunction{PyMem_Free()}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5517 \end{cfuncdesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5518 |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5519 In addition, the following macro sets are provided for calling the |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5520 Python memory allocator directly, without involving the C API functions |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5521 listed above. However, note that their use does not preserve binary |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5522 compatibility accross Python versions and is therefore deprecated in |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5523 extension modules. |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5524 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5525 \cfunction{PyMem_MALLOC()}, \cfunction{PyMem_REALLOC()}, \cfunction{PyMem_FREE()}. |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5526 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5527 \cfunction{PyMem_NEW()}, \cfunction{PyMem_RESIZE()}, \cfunction{PyMem_DEL()}. |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5528 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5529 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5530 \section{Examples \label{memoryExamples}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5531 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5532 Here is the example from section \ref{memoryOverview}, rewritten so |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5533 that the I/O buffer is allocated from the Python heap by using the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5534 first function set: |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5535 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5536 \begin{verbatim} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5537 PyObject *res; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5538 char *buf = (char *) PyMem_Malloc(BUFSIZ); /* for I/O */ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5539 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5540 if (buf == NULL) |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5541 return PyErr_NoMemory(); |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5542 /* ...Do some I/O operation involving buf... */ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5543 res = PyString_FromString(buf); |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5544 PyMem_Free(buf); /* allocated with PyMem_Malloc */ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5545 return res; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5546 \end{verbatim} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5547 |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5548 The same code using the type-oriented function set: |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5549 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5550 \begin{verbatim} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5551 PyObject *res; |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5552 char *buf = PyMem_New(char, BUFSIZ); /* for I/O */ |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5553 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5554 if (buf == NULL) |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5555 return PyErr_NoMemory(); |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5556 /* ...Do some I/O operation involving buf... */ |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5557 res = PyString_FromString(buf); |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5558 PyMem_Del(buf); /* allocated with PyMem_New */ |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5559 return res; |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5560 \end{verbatim} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5561 |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5562 Note that in the two examples above, the buffer is always |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5563 manipulated via functions belonging to the same set. Indeed, it |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5564 is required to use the same memory API family for a given |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5565 memory block, so that the risk of mixing different allocators is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5566 reduced to a minimum. The following code sequence contains two errors, |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5567 one of which is labeled as \emph{fatal} because it mixes two different |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5568 allocators operating on different heaps. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5569 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5570 \begin{verbatim} |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5571 char *buf1 = PyMem_New(char, BUFSIZ); |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5572 char *buf2 = (char *) malloc(BUFSIZ); |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5573 char *buf3 = (char *) PyMem_Malloc(BUFSIZ); |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5574 ... |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5575 PyMem_Del(buf3); /* Wrong -- should be PyMem_Free() */ |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5576 free(buf2); /* Right -- allocated via malloc() */ |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5577 free(buf1); /* Fatal -- should be PyMem_Del() */ |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5578 \end{verbatim} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5579 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5580 In addition to the functions aimed at handling raw memory blocks from |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5581 the Python heap, objects in Python are allocated and released with |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5582 \cfunction{PyObject_New()}, \cfunction{PyObject_NewVar()} and |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5583 \cfunction{PyObject_Del()}, or with their corresponding macros |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5584 \cfunction{PyObject_NEW()}, \cfunction{PyObject_NEW_VAR()} and |
|
13217
e2aee6190b19
Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents:
13150
diff
changeset
|
5585 \cfunction{PyObject_DEL()}. |
|
e2aee6190b19
Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents:
13150
diff
changeset
|
5586 |
|
e2aee6190b19
Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents:
13150
diff
changeset
|
5587 These will be explained in the next chapter on defining and |
|
e2aee6190b19
Uncomment some additions from Vladimir pertinent to 2.0 but not 1.5.2.
Fred Drake <fdrake@acm.org>
parents:
13150
diff
changeset
|
5588 implementing new object types in C. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5589 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5590 |
| 10163 | 5591 \chapter{Defining New Object Types \label{newTypes}} |
| 7308 | 5592 |
|
18785
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
5593 |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
5594 \section{Allocating Objects on the Heap |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
5595 \label{allocating-objects}} |
|
b465cd50cf36
Typo: PyArgs_ParseTuple --> PyArg_ParseTuple
Fred Drake <fdrake@acm.org>
parents:
18671
diff
changeset
|
5596 |
| 7782 | 5597 \begin{cfuncdesc}{PyObject*}{_PyObject_New}{PyTypeObject *type} |
| 7308 | 5598 \end{cfuncdesc} |
| 5599 | |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5600 \begin{cfuncdesc}{PyVarObject*}{_PyObject_NewVar}{PyTypeObject *type, int size} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5601 \end{cfuncdesc} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5602 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5603 \begin{cfuncdesc}{void}{_PyObject_Del}{PyObject *op} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5604 \end{cfuncdesc} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5605 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5606 \begin{cfuncdesc}{PyObject*}{PyObject_Init}{PyObject *op, |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5607 PyTypeObject *type} |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5608 Initialize a newly-allocated object \var{op} with its type and |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5609 initial reference. Returns the initialized object. If \var{type} |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5610 indicates that the object participates in the cyclic garbage |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5611 detector, it it added to the detector's set of observed objects. |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5612 Other fields of the object are not affected. |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5613 \end{cfuncdesc} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5614 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5615 \begin{cfuncdesc}{PyVarObject*}{PyObject_InitVar}{PyVarObject *op, |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5616 PyTypeObject *type, int size} |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5617 This does everything \cfunction{PyObject_Init()} does, and also |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5618 initializes the length information for a variable-size object. |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5619 \end{cfuncdesc} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5620 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5621 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_New}{TYPE, PyTypeObject *type} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5622 Allocate a new Python object using the C structure type \var{TYPE} |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5623 and the Python type object \var{type}. Fields not defined by the |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5624 Python object header are not initialized; the object's reference |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5625 count will be one. The size of the memory |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5626 allocation is determined from the \member{tp_basicsize} field of the |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5627 type object. |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5628 \end{cfuncdesc} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5629 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5630 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_NewVar}{TYPE, PyTypeObject *type, |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5631 int size} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5632 Allocate a new Python object using the C structure type \var{TYPE} |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5633 and the Python type object \var{type}. Fields not defined by the |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5634 Python object header are not initialized. The allocated memory |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5635 allows for the \var{TYPE} structure plus \var{size} fields of the |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5636 size given by the \member{tp_itemsize} field of \var{type}. This is |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5637 useful for implementing objects like tuples, which are able to |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5638 determine their size at construction time. Embedding the array of |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5639 fields into the same allocation decreases the number of allocations, |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5640 improving the memory management efficiency. |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5641 \end{cfuncdesc} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5642 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5643 \begin{cfuncdesc}{void}{PyObject_Del}{PyObject *op} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5644 Releases memory allocated to an object using |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5645 \cfunction{PyObject_New()} or \cfunction{PyObject_NewVar()}. This |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5646 is normally called from the \member{tp_dealloc} handler specified in |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5647 the object's type. The fields of the object should not be accessed |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5648 after this call as the memory is no longer a valid Python object. |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5649 \end{cfuncdesc} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5650 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5651 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW}{TYPE, PyTypeObject *type} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5652 Macro version of \cfunction{PyObject_New()}, to gain performance at |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5653 the expense of safety. This does not check \var{type} for a \NULL{} |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5654 value. |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5655 \end{cfuncdesc} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5656 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5657 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_NEW_VAR}{TYPE, PyTypeObject *type, |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5658 int size} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5659 Macro version of \cfunction{PyObject_NewVar()}, to gain performance |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5660 at the expense of safety. This does not check \var{type} for a |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5661 \NULL{} value. |
|
14526
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5662 \end{cfuncdesc} |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5663 |
|
ff4ae691be9b
Vladimir Marangozov <Vladimir.Marangozov@inrialpes.fr>:
Fred Drake <fdrake@acm.org>
parents:
14519
diff
changeset
|
5664 \begin{cfuncdesc}{void}{PyObject_DEL}{PyObject *op} |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5665 Macro version of \cfunction{PyObject_Del()}. |
| 7308 | 5666 \end{cfuncdesc} |
| 5667 | |
|
15444
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5668 \begin{cfuncdesc}{PyObject*}{Py_InitModule}{char *name, |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5669 PyMethodDef *methods} |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5670 Create a new module object based on a name and table of functions, |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5671 returning the new module object. |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5672 \end{cfuncdesc} |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5673 |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5674 \begin{cfuncdesc}{PyObject*}{Py_InitModule3}{char *name, |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5675 PyMethodDef *methods, |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5676 char *doc} |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5677 Create a new module object based on a name and table of functions, |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5678 returning the new module object. If \var{doc} is non-\NULL, it will |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5679 be used to define the docstring for the module. |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5680 \end{cfuncdesc} |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5681 |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5682 \begin{cfuncdesc}{PyObject*}{Py_InitModule4}{char *name, |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5683 PyMethodDef *methods, |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5684 char *doc, PyObject *self, |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5685 int apiver} |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5686 Create a new module object based on a name and table of functions, |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5687 returning the new module object. If \var{doc} is non-\NULL, it will |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5688 be used to define the docstring for the module. If \var{self} is |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5689 non-\NULL, it will passed to the functions of the module as their |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5690 (otherwise \NULL) first parameter. (This was added as an |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5691 experimental feature, and there are no known uses in the current |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5692 version of Python.) For \var{apiver}, the only value which should |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5693 be passed is defined by the constant \constant{PYTHON_API_VERSION}. |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5694 |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5695 \strong{Note:} Most uses of this function should probably be using |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5696 the \cfunction{Py_InitModule3()} instead; only use this if you are |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5697 sure you need it. |
|
7e514f1fe31f
Added documentation for the Py_InitModule*() family of functions.
Fred Drake <fdrake@acm.org>
parents:
15300
diff
changeset
|
5698 \end{cfuncdesc} |
|
8057
5aacdd097941
Some patches by Drew Csillag; plus a few of my own uncommitted changes.
Guido van Rossum <guido@python.org>
parents:
8029
diff
changeset
|
5699 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5700 DL_IMPORT |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5701 |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5702 \begin{cvardesc}{PyObject}{_Py_NoneStruct} |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5703 Object which is visible in Python as \code{None}. This should only |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5704 be accessed using the \code{Py_None} macro, which evaluates to a |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5705 pointer to this object. |
|
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
5706 \end{cvardesc} |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5707 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5708 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5709 \section{Common Object Structures \label{common-structs}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5710 |
|
5588
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
5711 PyObject, PyVarObject |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
5712 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
5713 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
|
5714 |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
5715 Typedefs: |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
5716 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
|
5717 intintargfunc, intobjargproc, intintobjargproc, objobjargproc, |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
5718 destructor, printfunc, getattrfunc, getattrofunc, setattrfunc, |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
5719 setattrofunc, cmpfunc, reprfunc, hashfunc |
|
53cdf94b652b
Just another checkin for backup. Nothing substantial yet.
Guido van Rossum <guido@python.org>
parents:
5536
diff
changeset
|
5720 |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5721 \begin{ctypedesc}{PyCFunction} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5722 Type of the functions used to implement most Python callables in C. |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5723 \end{ctypedesc} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5724 |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5725 \begin{ctypedesc}{PyMethodDef} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5726 Structure used to describe a method of an extension type. This |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5727 structure has four fields: |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5728 |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5729 \begin{tableiii}{l|l|l}{member}{Field}{C Type}{Meaning} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5730 \lineiii{ml_name}{char *}{name of the method} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5731 \lineiii{ml_meth}{PyCFunction}{pointer to the C implementation} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5732 \lineiii{ml_flags}{int}{flag bits indicating how the call should be |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5733 constructed} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5734 \lineiii{ml_doc}{char *}{points to the contents of the docstring} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5735 \end{tableiii} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5736 \end{ctypedesc} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5737 |
|
19301
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5738 The \var{ml_meth} is a C function pointer. The functions may be of |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5739 different types, but they always return \ctype{PyObject*}. If the |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5740 function is not of the \ctype{PyCFunction}, the compiler will require |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5741 a cast in the method table. Even though \ctype{PyCFunction} defines |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5742 the first parameter as \ctype{PyObject*}, it is common that the method |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5743 implementation uses a the specific C type of the \var{self} object. |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5744 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5745 The flags can have the following values. Only METH_VARARGS and |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5746 METH_KEYWORDS can be combined; the others can't. |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5747 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5748 \begin{datadesc}{METH_VARARGS} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5749 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5750 This is the typical calling convention, where the methods have the |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5751 type \ctype{PyMethodDef}. The function expects two \ctype{PyObject*}. |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5752 The first one is the \var{self} object for methods; for module |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5753 functions, it has the value given to \cfunction{PyInitModule4} (or |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5754 \NULL{} if \cfunction{PyInitModule} was used). The second parameter |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5755 (often called \var{args}) is a tuple object representing all |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5756 arguments. This parameter is typically processed using |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5757 \cfunction{PyArg_ParseTuple}. |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5758 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5759 \end{datadesc} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5760 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5761 \begin{datadesc}{METH_KEYWORDS} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5762 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5763 Methods with these flags must be of type |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5764 \ctype{PyCFunctionWithKeywords}. The function expects three |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5765 parameters: \var{self}, \var{args}, and a dictionary of all the keyword |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5766 arguments. The flag is typically combined with METH_VARARGS, and the |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5767 parameters are typically processed using |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5768 \cfunction{PyArg_ParseTupleAndKeywords}. |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5769 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5770 \end{datadesc} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5771 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5772 \begin{datadesc}{METH_NOARGS} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5773 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5774 Methods without parameters don't need to check whether arguments are |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5775 given if they are listed with the \code{METH_NOARGS} flag. They need |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5776 to be of type \ctype{PyNoArgsFunction}, i.e. they expect a single |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5777 \var{self} parameter. |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5778 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5779 \end{datadesc} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5780 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5781 \begin{datadesc}{METH_O} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5782 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5783 Methods with a single object argument can be listed with the |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5784 \code{METH_O} flag, instead of invoking \cfunction{PyArg_ParseTuple} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5785 with a \code{``O''} argument. They have the type \ctype{PyCFunction}, |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5786 with the \var{self} parameter, and a \ctype{PyObject*} parameter |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5787 representing the single argument. |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5788 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5789 \end{datadesc} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5790 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5791 \begin{datadesc}{METH_OLDARGS} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5792 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5793 This calling convention is deprecated. The method must be of type |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5794 \ctype{PyCFunction}. The second argument is \NULL{} if no arguments |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5795 are given, a single object if exactly one argument is given, and a |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5796 tuple of objects if more than one argument is given. |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5797 |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5798 \end{datadesc} |
|
b9701538f827
Patch #427190: Implement and use METH_NOARGS and METH_O.
Martin v. Löwis <martin@v.loewis.de>
parents:
19242
diff
changeset
|
5799 |
|
12930
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5800 \begin{cfuncdesc}{PyObject*}{Py_FindMethod}{PyMethodDef[] table, |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5801 PyObject *ob, char *name} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5802 Return a bound method object for an extension type implemented in C. |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5803 This function also handles the special attribute \member{__methods__}, |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5804 returning a list of all the method names defined in \var{table}. |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5805 \end{cfuncdesc} |
|
6618325574cb
Documented PySequence_List() and PySequence_Tuple().
Fred Drake <fdrake@acm.org>
parents:
12355
diff
changeset
|
5806 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5807 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5808 \section{Mapping Object Structures \label{mapping-structs}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5809 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5810 \begin{ctypedesc}{PyMappingMethods} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5811 Structure used to hold pointers to the functions used to implement the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5812 mapping protocol for an extension type. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5813 \end{ctypedesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5814 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5815 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5816 \section{Number Object Structures \label{number-structs}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5817 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5818 \begin{ctypedesc}{PyNumberMethods} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5819 Structure used to hold pointers to the functions an extension type |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5820 uses to implement the number protocol. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5821 \end{ctypedesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5822 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5823 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5824 \section{Sequence Object Structures \label{sequence-structs}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5825 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5826 \begin{ctypedesc}{PySequenceMethods} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5827 Structure used to hold pointers to the functions which an object uses |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5828 to implement the sequence protocol. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5829 \end{ctypedesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5830 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5831 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5832 \section{Buffer Object Structures \label{buffer-structs}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5833 \sectionauthor{Greg J. Stein}{greg@lyra.org} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5834 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5835 The buffer interface exports a model where an object can expose its |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5836 internal data as a set of chunks of data, where each chunk is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5837 specified as a pointer/length pair. These chunks are called |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5838 \dfn{segments} and are presumed to be non-contiguous in memory. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5839 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5840 If an object does not export the buffer interface, then its |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5841 \member{tp_as_buffer} member in the \ctype{PyTypeObject} structure |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5842 should be \NULL{}. Otherwise, the \member{tp_as_buffer} will point to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5843 a \ctype{PyBufferProcs} structure. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5844 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5845 \strong{Note:} It is very important that your |
|
17118
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5846 \ctype{PyTypeObject} structure uses \constant{Py_TPFLAGS_DEFAULT} for |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5847 the value of the \member{tp_flags} member rather than \code{0}. This |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5848 tells the Python runtime that your \ctype{PyBufferProcs} structure |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5849 contains the \member{bf_getcharbuffer} slot. Older versions of Python |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5850 did not have this member, so a new Python interpreter using an old |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5851 extension needs to be able to test for its presence before using it. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5852 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5853 \begin{ctypedesc}{PyBufferProcs} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5854 Structure used to hold the function pointers which define an |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5855 implementation of the buffer protocol. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5856 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5857 The first slot is \member{bf_getreadbuffer}, of type |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5858 \ctype{getreadbufferproc}. If this slot is \NULL{}, then the object |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5859 does not support reading from the internal data. This is |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5860 non-sensical, so implementors should fill this in, but callers should |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5861 test that the slot contains a non-\NULL{} value. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5862 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5863 The next slot is \member{bf_getwritebuffer} having type |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5864 \ctype{getwritebufferproc}. This slot may be \NULL{} if the object |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5865 does not allow writing into its returned buffers. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5866 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5867 The third slot is \member{bf_getsegcount}, with type |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5868 \ctype{getsegcountproc}. This slot must not be \NULL{} and is used to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5869 inform the caller how many segments the object contains. Simple |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5870 objects such as \ctype{PyString_Type} and |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5871 \ctype{PyBuffer_Type} objects contain a single segment. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5872 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5873 The last slot is \member{bf_getcharbuffer}, of type |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5874 \ctype{getcharbufferproc}. This slot will only be present if the |
|
17118
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5875 \constant{Py_TPFLAGS_HAVE_GETCHARBUFFER} flag is present in the |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5876 \member{tp_flags} field of the object's \ctype{PyTypeObject}. Before using |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5877 this slot, the caller should test whether it is present by using the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5878 \cfunction{PyType_HasFeature()}\ttindex{PyType_HasFeature()} function. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5879 If present, it may be \NULL, indicating that the object's contents |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5880 cannot be used as \emph{8-bit characters}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5881 The slot function may also raise an error if the object's contents |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5882 cannot be interpreted as 8-bit characters. For example, if the object |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5883 is an array which is configured to hold floating point values, an |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5884 exception may be raised if a caller attempts to use |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5885 \member{bf_getcharbuffer} to fetch a sequence of 8-bit characters. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5886 This notion of exporting the internal buffers as ``text'' is used to |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5887 distinguish between objects that are binary in nature, and those which |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5888 have character-based content. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5889 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5890 \strong{Note:} The current policy seems to state that these characters |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5891 may be multi-byte characters. This implies that a buffer size of |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5892 \var{N} does not mean there are \var{N} characters present. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5893 \end{ctypedesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5894 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5895 \begin{datadesc}{Py_TPFLAGS_HAVE_GETCHARBUFFER} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5896 Flag bit set in the type structure to indicate that the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5897 \member{bf_getcharbuffer} slot is known. This being set does not |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5898 indicate that the object supports the buffer interface or that the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5899 \member{bf_getcharbuffer} slot is non-\NULL. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5900 \end{datadesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5901 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5902 \begin{ctypedesc}[getreadbufferproc]{int (*getreadbufferproc) |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5903 (PyObject *self, int segment, void **ptrptr)} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5904 Return a pointer to a readable segment of the buffer. This function |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5905 is allowed to raise an exception, in which case it must return |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5906 \code{-1}. The \var{segment} which is passed must be zero or |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5907 positive, and strictly less than the number of segments returned by |
|
17336
2146a73ce35c
Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents:
17307
diff
changeset
|
5908 the \member{bf_getsegcount} slot function. On success, it returns the |
|
2146a73ce35c
Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents:
17307
diff
changeset
|
5909 length of the buffer memory, and sets \code{*\var{ptrptr}} to a |
|
2146a73ce35c
Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents:
17307
diff
changeset
|
5910 pointer to that memory. |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5911 \end{ctypedesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5912 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5913 \begin{ctypedesc}[getwritebufferproc]{int (*getwritebufferproc) |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5914 (PyObject *self, int segment, void **ptrptr)} |
|
17336
2146a73ce35c
Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents:
17307
diff
changeset
|
5915 Return a pointer to a writable memory buffer in \code{*\var{ptrptr}}, |
|
2146a73ce35c
Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents:
17307
diff
changeset
|
5916 and the length of that segment as the function return value. |
|
2146a73ce35c
Correct the documentation for getreadbufferproc and getwritebufferproc.
Greg Stein <gstein@lyra.org>
parents:
17307
diff
changeset
|
5917 The memory buffer must correspond to buffer segment \var{segment}. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
5918 Must return \code{-1} and set an exception on error. |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
5919 \exception{TypeError} should be raised if the object only supports |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
5920 read-only buffers, and \exception{SystemError} should be raised when |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
5921 \var{segment} specifies a segment that doesn't exist. |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
5922 % Why doesn't it raise ValueError for this one? |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5923 % GJS: because you shouldn't be calling it with an invalid |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5924 % segment. That indicates a blatant programming error in the C |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5925 % code. |
|
11176
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
5926 \end{ctypedesc} |
|
64b15e9091a9
Started documentation on buffer objects & types. Very preliminary.
Fred Drake <fdrake@acm.org>
parents:
11168
diff
changeset
|
5927 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5928 \begin{ctypedesc}[getsegcountproc]{int (*getsegcountproc) |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5929 (PyObject *self, int *lenp)} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5930 Return the number of memory segments which comprise the buffer. If |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5931 \var{lenp} is not \NULL, the implementation must report the sum of the |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5932 sizes (in bytes) of all segments in \code{*\var{lenp}}. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5933 The function cannot fail. |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5934 \end{ctypedesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5935 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5936 \begin{ctypedesc}[getcharbufferproc]{int (*getcharbufferproc) |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5937 (PyObject *self, int segment, const char **ptrptr)} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5938 \end{ctypedesc} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5939 |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
5940 |
|
18944
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5941 \section{Supporting the Iterator Protocol |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5942 \label{supporting-iteration}} |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5943 |
|
a0819708fe9c
Move away from apply() to using extended call syntax for some example
Fred Drake <fdrake@acm.org>
parents:
18785
diff
changeset
|
5944 |
|
17118
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5945 \section{Supporting Cyclic Garbarge Collection |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5946 \label{supporting-cycle-detection}} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5947 |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5948 Python's support for detecting and collecting garbage which involves |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5949 circular references requires support from object types which are |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5950 ``containers'' for other objects which may also be containers. Types |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5951 which do not store references to other objects, or which only store |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5952 references to atomic types (such as numbers or strings), do not need |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5953 to provide any explicit support for garbage collection. |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5954 |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5955 To create a container type, the \member{tp_flags} field of the type |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5956 object must include the \constant{Py_TPFLAGS_HAVE_GC} and provide an |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5957 implementation of the \member{tp_traverse} handler. If instances of the |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5958 type are mutable, a \member{tp_clear} implementation must also be |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5959 provided. |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5960 |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5961 \begin{datadesc}{Py_TPFLAGS_HAVE_GC} |
|
17118
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5962 Objects with a type with this flag set must conform with the rules |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5963 documented here. For convenience these objects will be referred to |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5964 as container objects. |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5965 \end{datadesc} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5966 |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
5967 Constructors for container types must conform to two rules: |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
5968 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
5969 \begin{enumerate} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
5970 \item The memory for the object must be allocated using |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5971 \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_VarNew()}. |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
5972 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
5973 \item Once all the fields which may contain references to other |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
5974 containers are initialized, it must call |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5975 \cfunction{PyObject_GC_Track()}. |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
5976 \end{enumerate} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
5977 |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5978 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_New}{TYPE, PyTypeObject *type} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5979 Analogous to \cfunction{PyObject_New()} but for container objects with |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5980 the \constant{Py_TPFLAGS_HAVE_GC} flag set. |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5981 \end{cfuncdesc} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5982 |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5983 \begin{cfuncdesc}{\var{TYPE}*}{PyObject_GC_NewVar}{TYPE, PyTypeObject *type, |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5984 int size} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5985 Analogous to \cfunction{PyObject_NewVar()} but for container objects |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5986 with the \constant{Py_TPFLAGS_HAVE_GC} flag set. |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5987 \end{cfuncdesc} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5988 |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5989 \begin{cfuncdesc}{PyVarObject *}{PyObject_GC_Resize}{PyVarObject *op, int} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5990 Resize an object allocated by \cfunction{PyObject_NewVar()}. Returns |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5991 the resized object or \NULL{} on failure. |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5992 \end{cfuncdesc} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5993 |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
5994 \begin{cfuncdesc}{void}{PyObject_GC_Track}{PyObject *op} |
|
17118
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5995 Adds the object \var{op} to the set of container objects tracked by |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5996 the collector. The collector can run at unexpected times so objects |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5997 must be valid while being tracked. This should be called once all |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5998 the fields followed by the \member{tp_traverse} handler become valid, |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
5999 usually near the end of the constructor. |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6000 \end{cfuncdesc} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6001 |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6002 \begin{cfuncdesc}{void}{_PyObject_GC_TRACK}{PyObject *op} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6003 A macro version of \cfunction{PyObject_GC_Track()}. It should not be |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6004 used for extension modules. |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6005 \end{cfuncdesc} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6006 |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6007 Similarly, the deallocator for the object must conform to a similar |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6008 pair of rules: |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6009 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6010 \begin{enumerate} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6011 \item Before fields which refer to other containers are invalidated, |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6012 \cfunction{PyObject_GC_UnTrack()} must be called. |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6013 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6014 \item The object's memory must be deallocated using |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6015 \cfunction{PyObject_GC_Del()}. |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6016 \end{enumerate} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6017 |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6018 \begin{cfuncdesc}{void}{PyObject_GC_Del}{PyObject *op} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6019 Releases memory allocated to an object using |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6020 \cfunction{PyObject_GC_New()} or \cfunction{PyObject_GC_NewVar()}. |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6021 \end{cfuncdesc} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6022 |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6023 \begin{cfuncdesc}{void}{PyObject_GC_UnTrack}{PyObject *op} |
|
17118
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6024 Remove the object \var{op} from the set of container objects tracked |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6025 by the collector. Note that \cfunction{PyObject_GC_Track()} can be |
|
17118
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6026 called again on this object to add it back to the set of tracked |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6027 objects. The deallocator (\member{tp_dealloc} handler) should call |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6028 this for the object before any of the fields used by the |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6029 \member{tp_traverse} handler become invalid. |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6030 \end{cfuncdesc} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6031 |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6032 \begin{cfuncdesc}{void}{_PyObject_GC_UNTRACK}{PyObject *op} |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6033 A macro version of \cfunction{PyObject_GC_UnTrack()}. It should not be |
|
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6034 used for extension modules. |
|
17118
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6035 \end{cfuncdesc} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6036 |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6037 The \member{tp_traverse} handler accepts a function parameter of this |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6038 type: |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6039 |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6040 \begin{ctypedesc}[visitproc]{int (*visitproc)(PyObject *object, void *arg)} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6041 Type of the visitor function passed to the \member{tp_traverse} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6042 handler. The function should be called with an object to traverse |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6043 as \var{object} and the third parameter to the \member{tp_traverse} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6044 handler as \var{arg}. |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6045 \end{ctypedesc} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6046 |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6047 The \member{tp_traverse} handler must have the following type: |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6048 |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6049 \begin{ctypedesc}[traverseproc]{int (*traverseproc)(PyObject *self, |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6050 visitproc visit, void *arg)} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6051 Traversal function for a container object. Implementations must |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6052 call the \var{visit} function for each object directly contained by |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6053 \var{self}, with the parameters to \var{visit} being the contained |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6054 object and the \var{arg} value passed to the handler. If |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6055 \var{visit} returns a non-zero value then an error has occurred and |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6056 that value should be returned immediately. |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6057 \end{ctypedesc} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6058 |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6059 The \member{tp_clear} handler must be of the \ctype{inquiry} type, or |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6060 \NULL{} if the object is immutable. |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6061 |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6062 \begin{ctypedesc}[inquiry]{int (*inquiry)(PyObject *self)} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6063 Drop references that may have created reference cycles. Immutable |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6064 objects do not have to define this method since they can never |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6065 directly create reference cycles. Note that the object must still |
|
18447
ca2ea75df3f2
Document PyObject_New(), PyObject_NewVar(), PyObject_Init(),
Fred Drake <fdrake@acm.org>
parents:
18438
diff
changeset
|
6066 be valid after calling this method (don't just call |
|
17118
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6067 \cfunction{Py_DECREF()} on a reference). The collector will call |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6068 this method if it detects that this object is involved in a |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6069 reference cycle. |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6070 \end{ctypedesc} |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6071 |
|
f9a07e99907e
Integrated an expanded version of some text from Neil Schemenauer about
Fred Drake <fdrake@acm.org>
parents:
17057
diff
changeset
|
6072 |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6073 \subsection{Example Cycle Collector Support |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6074 \label{example-cycle-support}} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6075 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6076 This example shows only enough of the implementation of an extension |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6077 type to show how the garbage collector support needs to be added. It |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6078 shows the definition of the object structure, the |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6079 \member{tp_traverse}, \member{tp_clear} and \member{tp_dealloc} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6080 implementations, the type structure, and a constructor --- the module |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6081 initialization needed to export the constructor to Python is not shown |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6082 as there are no special considerations there for the collector. To |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6083 make this interesting, assume that the module exposes ways for the |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6084 \member{container} field of the object to be modified. Note that |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6085 since no checks are made on the type of the object used to initialize |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6086 \member{container}, we have to assume that it may be a container. |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6087 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6088 \begin{verbatim} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6089 #include "Python.h" |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6090 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6091 typedef struct { |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6092 PyObject_HEAD |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6093 PyObject *container; |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6094 } MyObject; |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6095 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6096 static int |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6097 my_traverse(MyObject *self, visitproc visit, void *arg) |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6098 { |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6099 if (self->container != NULL) |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6100 return visit(self->container, arg); |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6101 else |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6102 return 0; |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6103 } |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6104 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6105 static int |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6106 my_clear(MyObject *self) |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6107 { |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6108 Py_XDECREF(self->container); |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6109 self->container = NULL; |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6110 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6111 return 0; |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6112 } |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6113 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6114 static void |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6115 my_dealloc(MyObject *self) |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6116 { |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6117 PyObject_GC_UnTrack((PyObject *) self); |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6118 Py_XDECREF(self->container); |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6119 PyObject_GC_Del(self); |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6120 } |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6121 \end{verbatim} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6122 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6123 \begin{verbatim} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6124 statichere PyTypeObject |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6125 MyObject_Type = { |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6126 PyObject_HEAD_INIT(NULL) |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6127 0, |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6128 "MyObject", |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6129 sizeof(MyObject), |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6130 0, |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6131 (destructor)my_dealloc, /* tp_dealloc */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6132 0, /* tp_print */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6133 0, /* tp_getattr */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6134 0, /* tp_setattr */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6135 0, /* tp_compare */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6136 0, /* tp_repr */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6137 0, /* tp_as_number */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6138 0, /* tp_as_sequence */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6139 0, /* tp_as_mapping */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6140 0, /* tp_hash */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6141 0, /* tp_call */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6142 0, /* tp_str */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6143 0, /* tp_getattro */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6144 0, /* tp_setattro */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6145 0, /* tp_as_buffer */ |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6146 Py_TPFLAGS_DEFAULT | Py_TPFLAGS_HAVE_GC, |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6147 0, /* tp_doc */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6148 (traverseproc)my_traverse, /* tp_traverse */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6149 (inquiry)my_clear, /* tp_clear */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6150 0, /* tp_richcompare */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6151 0, /* tp_weaklistoffset */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6152 }; |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6153 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6154 /* This constructor should be made accessible from Python. */ |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6155 static PyObject * |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6156 new_object(PyObject *unused, PyObject *args) |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6157 { |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6158 PyObject *container = NULL; |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6159 MyObject *result = NULL; |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6160 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6161 if (PyArg_ParseTuple(args, "|O:new_object", &container)) { |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6162 result = PyObject_GC_New(MyObject, &MyObject_Type); |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6163 if (result != NULL) { |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6164 result->container = container; |
|
19607
43fe9377e2cf
Update documentation for GC API. Closes SF patch #421893.
Neil Schemenauer <nascheme@enme.ucalgary.ca>
parents:
19524
diff
changeset
|
6165 PyObject_GC_Track(result); |
|
17147
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6166 } |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6167 } |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6168 return (PyObject *) result; |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6169 } |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6170 \end{verbatim} |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6171 |
|
349c8788604e
Be more clear about the specific rules for supporting the cyclic GC in an
Fred Drake <fdrake@acm.org>
parents:
17118
diff
changeset
|
6172 |
|
12222
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
6173 % \chapter{Debugging \label{debugging}} |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
6174 % |
|
3e9a1c1a9f56
Merge in changes from the 1.5.2p2 release.
Fred Drake <fdrake@acm.org>
parents:
12200
diff
changeset
|
6175 % 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
|
6176 |
|
f349bf0e9322
A whole bunch of typos fixed by Andrew Kuchling.
Guido van Rossum <guido@python.org>
parents:
6653
diff
changeset
|
6177 |
|
14736
2b9a890162b0
Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents:
14696
diff
changeset
|
6178 \appendix |
|
2b9a890162b0
Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents:
14696
diff
changeset
|
6179 \chapter{Reporting Bugs} |
|
2b9a890162b0
Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents:
14696
diff
changeset
|
6180 \input{reportingbugs} |
|
2b9a890162b0
Include the new text on reporting bugs in a few useful places.
Fred Drake <fdrake@acm.org>
parents:
14696
diff
changeset
|
6181 |
|
18192
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
6182 \chapter{History and License} |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
6183 \input{license} |
|
19bc63a84439
Move license information to a less annoying location in the document.
Fred Drake <fdrake@acm.org>
parents:
18020
diff
changeset
|
6184 |
|
15953
8349b4dfc51a
Undoing the whitespace patches which sneaked into the earlier patch.
Marc-André Lemburg <mal@egenix.com>
parents:
15952
diff
changeset
|
6185 \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
|
6186 |
|
c6f04e965508
Made a start with api.tex, the Python-C API Reference Manual.
Guido van Rossum <guido@python.org>
parents:
diff
changeset
|
6187 \end{document} |