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