Fred Drake | 3adf79e | 2001-10-12 19:01:43 +0000 | [diff] [blame] | 1 | \chapter{Introduction \label{intro}} |
| 2 | |
| 3 | |
| 4 | The Application Programmer's Interface to Python gives C and |
| 5 | \Cpp{} programmers access to the Python interpreter at a variety of |
Fred Drake | c37b65e | 2001-11-28 07:26:15 +0000 | [diff] [blame] | 6 | levels. The API is equally usable from \Cpp, but for brevity it is |
Fred Drake | 3adf79e | 2001-10-12 19:01:43 +0000 | [diff] [blame] | 7 | generally referred to as the Python/C API. There are two |
| 8 | fundamentally different reasons for using the Python/C API. The first |
| 9 | reason is to write \emph{extension modules} for specific purposes; |
| 10 | these are C modules that extend the Python interpreter. This is |
| 11 | probably the most common use. The second reason is to use Python as a |
| 12 | component in a larger application; this technique is generally |
| 13 | referred to as \dfn{embedding} Python in an application. |
| 14 | |
| 15 | Writing an extension module is a relatively well-understood process, |
| 16 | where a ``cookbook'' approach works well. There are several tools |
| 17 | that automate the process to some extent. While people have embedded |
| 18 | Python in other applications since its early existence, the process of |
| 19 | embedding Python is less straightforward than writing an extension. |
| 20 | |
| 21 | Many API functions are useful independent of whether you're embedding |
| 22 | or extending Python; moreover, most applications that embed Python |
| 23 | will need to provide a custom extension as well, so it's probably a |
| 24 | good idea to become familiar with writing an extension before |
| 25 | attempting to embed Python in a real application. |
| 26 | |
| 27 | |
| 28 | \section{Include Files \label{includes}} |
| 29 | |
| 30 | All function, type and macro definitions needed to use the Python/C |
| 31 | API are included in your code by the following line: |
| 32 | |
| 33 | \begin{verbatim} |
| 34 | #include "Python.h" |
| 35 | \end{verbatim} |
| 36 | |
| 37 | This implies inclusion of the following standard headers: |
| 38 | \code{<stdio.h>}, \code{<string.h>}, \code{<errno.h>}, |
| 39 | \code{<limits.h>}, and \code{<stdlib.h>} (if available). |
| 40 | Since Python may define some pre-processor definitions which affect |
| 41 | the standard headers on some systems, you must include \file{Python.h} |
| 42 | before any standard headers are included. |
| 43 | |
| 44 | All user visible names defined by Python.h (except those defined by |
| 45 | the included standard headers) have one of the prefixes \samp{Py} or |
| 46 | \samp{_Py}. Names beginning with \samp{_Py} are for internal use by |
| 47 | the Python implementation and should not be used by extension writers. |
| 48 | Structure member names do not have a reserved prefix. |
| 49 | |
| 50 | \strong{Important:} user code should never define names that begin |
| 51 | with \samp{Py} or \samp{_Py}. This confuses the reader, and |
| 52 | jeopardizes the portability of the user code to future Python |
| 53 | versions, which may define additional names beginning with one of |
| 54 | these prefixes. |
| 55 | |
| 56 | The header files are typically installed with Python. On \UNIX, these |
| 57 | are located in the directories |
| 58 | \file{\envvar{prefix}/include/python\var{version}/} and |
| 59 | \file{\envvar{exec_prefix}/include/python\var{version}/}, where |
| 60 | \envvar{prefix} and \envvar{exec_prefix} are defined by the |
| 61 | corresponding parameters to Python's \program{configure} script and |
| 62 | \var{version} is \code{sys.version[:3]}. On Windows, the headers are |
| 63 | installed in \file{\envvar{prefix}/include}, where \envvar{prefix} is |
| 64 | the installation directory specified to the installer. |
| 65 | |
| 66 | To include the headers, place both directories (if different) on your |
| 67 | compiler's search path for includes. Do \emph{not} place the parent |
| 68 | directories on the search path and then use |
| 69 | \samp{\#include <python\shortversion/Python.h>}; this will break on |
| 70 | multi-platform builds since the platform independent headers under |
| 71 | \envvar{prefix} include the platform specific headers from |
| 72 | \envvar{exec_prefix}. |
| 73 | |
| 74 | \Cpp{} users should note that though the API is defined entirely using |
| 75 | C, the header files do properly declare the entry points to be |
| 76 | \code{extern "C"}, so there is no need to do anything special to use |
| 77 | the API from \Cpp. |
| 78 | |
| 79 | |
| 80 | \section{Objects, Types and Reference Counts \label{objects}} |
| 81 | |
| 82 | Most Python/C API functions have one or more arguments as well as a |
| 83 | return value of type \ctype{PyObject*}. This type is a pointer |
| 84 | to an opaque data type representing an arbitrary Python |
| 85 | object. Since all Python object types are treated the same way by the |
| 86 | Python language in most situations (e.g., assignments, scope rules, |
| 87 | and argument passing), it is only fitting that they should be |
| 88 | represented by a single C type. Almost all Python objects live on the |
| 89 | heap: you never declare an automatic or static variable of type |
| 90 | \ctype{PyObject}, only pointer variables of type \ctype{PyObject*} can |
| 91 | be declared. The sole exception are the type objects\obindex{type}; |
| 92 | since these must never be deallocated, they are typically static |
| 93 | \ctype{PyTypeObject} objects. |
| 94 | |
| 95 | All Python objects (even Python integers) have a \dfn{type} and a |
| 96 | \dfn{reference count}. An object's type determines what kind of object |
| 97 | it is (e.g., an integer, a list, or a user-defined function; there are |
| 98 | many more as explained in the \citetitle[../ref/ref.html]{Python |
| 99 | Reference Manual}). For each of the well-known types there is a macro |
| 100 | to check whether an object is of that type; for instance, |
| 101 | \samp{PyList_Check(\var{a})} is true if (and only if) the object |
| 102 | pointed to by \var{a} is a Python list. |
| 103 | |
| 104 | |
| 105 | \subsection{Reference Counts \label{refcounts}} |
| 106 | |
| 107 | The reference count is important because today's computers have a |
| 108 | finite (and often severely limited) memory size; it counts how many |
| 109 | different places there are that have a reference to an object. Such a |
| 110 | place could be another object, or a global (or static) C variable, or |
| 111 | a local variable in some C function. When an object's reference count |
| 112 | becomes zero, the object is deallocated. If it contains references to |
| 113 | other objects, their reference count is decremented. Those other |
| 114 | objects may be deallocated in turn, if this decrement makes their |
| 115 | reference count become zero, and so on. (There's an obvious problem |
| 116 | with objects that reference each other here; for now, the solution is |
| 117 | ``don't do that.'') |
| 118 | |
| 119 | Reference counts are always manipulated explicitly. The normal way is |
| 120 | to use the macro \cfunction{Py_INCREF()}\ttindex{Py_INCREF()} to |
| 121 | increment an object's reference count by one, and |
| 122 | \cfunction{Py_DECREF()}\ttindex{Py_DECREF()} to decrement it by |
| 123 | one. The \cfunction{Py_DECREF()} macro is considerably more complex |
| 124 | than the incref one, since it must check whether the reference count |
| 125 | becomes zero and then cause the object's deallocator to be called. |
| 126 | The deallocator is a function pointer contained in the object's type |
| 127 | structure. The type-specific deallocator takes care of decrementing |
| 128 | the reference counts for other objects contained in the object if this |
| 129 | is a compound object type, such as a list, as well as performing any |
| 130 | additional finalization that's needed. There's no chance that the |
| 131 | reference count can overflow; at least as many bits are used to hold |
| 132 | the reference count as there are distinct memory locations in virtual |
| 133 | memory (assuming \code{sizeof(long) >= sizeof(char*)}). Thus, the |
| 134 | reference count increment is a simple operation. |
| 135 | |
| 136 | It is not necessary to increment an object's reference count for every |
| 137 | local variable that contains a pointer to an object. In theory, the |
| 138 | object's reference count goes up by one when the variable is made to |
| 139 | point to it and it goes down by one when the variable goes out of |
| 140 | scope. However, these two cancel each other out, so at the end the |
| 141 | reference count hasn't changed. The only real reason to use the |
| 142 | reference count is to prevent the object from being deallocated as |
| 143 | long as our variable is pointing to it. If we know that there is at |
| 144 | least one other reference to the object that lives at least as long as |
| 145 | our variable, there is no need to increment the reference count |
| 146 | temporarily. An important situation where this arises is in objects |
| 147 | that are passed as arguments to C functions in an extension module |
| 148 | that are called from Python; the call mechanism guarantees to hold a |
| 149 | reference to every argument for the duration of the call. |
| 150 | |
| 151 | However, a common pitfall is to extract an object from a list and |
| 152 | hold on to it for a while without incrementing its reference count. |
| 153 | Some other operation might conceivably remove the object from the |
| 154 | list, decrementing its reference count and possible deallocating it. |
| 155 | The real danger is that innocent-looking operations may invoke |
| 156 | arbitrary Python code which could do this; there is a code path which |
| 157 | allows control to flow back to the user from a \cfunction{Py_DECREF()}, |
| 158 | so almost any operation is potentially dangerous. |
| 159 | |
| 160 | A safe approach is to always use the generic operations (functions |
| 161 | whose name begins with \samp{PyObject_}, \samp{PyNumber_}, |
| 162 | \samp{PySequence_} or \samp{PyMapping_}). These operations always |
| 163 | increment the reference count of the object they return. This leaves |
| 164 | the caller with the responsibility to call |
| 165 | \cfunction{Py_DECREF()} when they are done with the result; this soon |
| 166 | becomes second nature. |
| 167 | |
| 168 | |
| 169 | \subsubsection{Reference Count Details \label{refcountDetails}} |
| 170 | |
| 171 | The reference count behavior of functions in the Python/C API is best |
| 172 | explained in terms of \emph{ownership of references}. Note that we |
| 173 | talk of owning references, never of owning objects; objects are always |
| 174 | shared! When a function owns a reference, it has to dispose of it |
| 175 | properly --- either by passing ownership on (usually to its caller) or |
| 176 | by calling \cfunction{Py_DECREF()} or \cfunction{Py_XDECREF()}. When |
| 177 | a function passes ownership of a reference on to its caller, the |
| 178 | caller is said to receive a \emph{new} reference. When no ownership |
| 179 | is transferred, the caller is said to \emph{borrow} the reference. |
| 180 | Nothing needs to be done for a borrowed reference. |
| 181 | |
| 182 | Conversely, when a calling function passes it a reference to an |
| 183 | object, there are two possibilities: the function \emph{steals} a |
| 184 | reference to the object, or it does not. Few functions steal |
| 185 | references; the two notable exceptions are |
| 186 | \cfunction{PyList_SetItem()}\ttindex{PyList_SetItem()} and |
| 187 | \cfunction{PyTuple_SetItem()}\ttindex{PyTuple_SetItem()}, which |
| 188 | steal a reference to the item (but not to the tuple or list into which |
| 189 | the item is put!). These functions were designed to steal a reference |
| 190 | because of a common idiom for populating a tuple or list with newly |
| 191 | created objects; for example, the code to create the tuple \code{(1, |
| 192 | 2, "three")} could look like this (forgetting about error handling for |
| 193 | the moment; a better way to code this is shown below): |
| 194 | |
| 195 | \begin{verbatim} |
| 196 | PyObject *t; |
| 197 | |
| 198 | t = PyTuple_New(3); |
| 199 | PyTuple_SetItem(t, 0, PyInt_FromLong(1L)); |
| 200 | PyTuple_SetItem(t, 1, PyInt_FromLong(2L)); |
| 201 | PyTuple_SetItem(t, 2, PyString_FromString("three")); |
| 202 | \end{verbatim} |
| 203 | |
| 204 | Incidentally, \cfunction{PyTuple_SetItem()} is the \emph{only} way to |
| 205 | set tuple items; \cfunction{PySequence_SetItem()} and |
| 206 | \cfunction{PyObject_SetItem()} refuse to do this since tuples are an |
| 207 | immutable data type. You should only use |
| 208 | \cfunction{PyTuple_SetItem()} for tuples that you are creating |
| 209 | yourself. |
| 210 | |
| 211 | Equivalent code for populating a list can be written using |
| 212 | \cfunction{PyList_New()} and \cfunction{PyList_SetItem()}. Such code |
| 213 | can also use \cfunction{PySequence_SetItem()}; this illustrates the |
| 214 | difference between the two (the extra \cfunction{Py_DECREF()} calls): |
| 215 | |
| 216 | \begin{verbatim} |
| 217 | PyObject *l, *x; |
| 218 | |
| 219 | l = PyList_New(3); |
| 220 | x = PyInt_FromLong(1L); |
| 221 | PySequence_SetItem(l, 0, x); Py_DECREF(x); |
| 222 | x = PyInt_FromLong(2L); |
| 223 | PySequence_SetItem(l, 1, x); Py_DECREF(x); |
| 224 | x = PyString_FromString("three"); |
| 225 | PySequence_SetItem(l, 2, x); Py_DECREF(x); |
| 226 | \end{verbatim} |
| 227 | |
| 228 | You might find it strange that the ``recommended'' approach takes more |
| 229 | code. However, in practice, you will rarely use these ways of |
| 230 | creating and populating a tuple or list. There's a generic function, |
| 231 | \cfunction{Py_BuildValue()}, that can create most common objects from |
| 232 | C values, directed by a \dfn{format string}. For example, the |
| 233 | above two blocks of code could be replaced by the following (which |
| 234 | also takes care of the error checking): |
| 235 | |
| 236 | \begin{verbatim} |
| 237 | PyObject *t, *l; |
| 238 | |
| 239 | t = Py_BuildValue("(iis)", 1, 2, "three"); |
| 240 | l = Py_BuildValue("[iis]", 1, 2, "three"); |
| 241 | \end{verbatim} |
| 242 | |
| 243 | It is much more common to use \cfunction{PyObject_SetItem()} and |
| 244 | friends with items whose references you are only borrowing, like |
| 245 | arguments that were passed in to the function you are writing. In |
| 246 | that case, their behaviour regarding reference counts is much saner, |
| 247 | since you don't have to increment a reference count so you can give a |
| 248 | reference away (``have it be stolen''). For example, this function |
| 249 | sets all items of a list (actually, any mutable sequence) to a given |
| 250 | item: |
| 251 | |
| 252 | \begin{verbatim} |
Fred Drake | 847c51a | 2001-10-25 15:53:44 +0000 | [diff] [blame] | 253 | int |
| 254 | set_all(PyObject *target, PyObject *item) |
Fred Drake | 3adf79e | 2001-10-12 19:01:43 +0000 | [diff] [blame] | 255 | { |
| 256 | int i, n; |
| 257 | |
| 258 | n = PyObject_Length(target); |
| 259 | if (n < 0) |
| 260 | return -1; |
| 261 | for (i = 0; i < n; i++) { |
| 262 | if (PyObject_SetItem(target, i, item) < 0) |
| 263 | return -1; |
| 264 | } |
| 265 | return 0; |
| 266 | } |
| 267 | \end{verbatim} |
| 268 | \ttindex{set_all()} |
| 269 | |
| 270 | The situation is slightly different for function return values. |
| 271 | While passing a reference to most functions does not change your |
| 272 | ownership responsibilities for that reference, many functions that |
| 273 | return a referece to an object give you ownership of the reference. |
| 274 | The reason is simple: in many cases, the returned object is created |
| 275 | on the fly, and the reference you get is the only reference to the |
| 276 | object. Therefore, the generic functions that return object |
| 277 | references, like \cfunction{PyObject_GetItem()} and |
| 278 | \cfunction{PySequence_GetItem()}, always return a new reference (the |
| 279 | caller becomes the owner of the reference). |
| 280 | |
| 281 | It is important to realize that whether you own a reference returned |
| 282 | by a function depends on which function you call only --- \emph{the |
| 283 | plumage} (the type of the type of the object passed as an |
| 284 | argument to the function) \emph{doesn't enter into it!} Thus, if you |
| 285 | extract an item from a list using \cfunction{PyList_GetItem()}, you |
| 286 | don't own the reference --- but if you obtain the same item from the |
| 287 | same list using \cfunction{PySequence_GetItem()} (which happens to |
| 288 | take exactly the same arguments), you do own a reference to the |
| 289 | returned object. |
| 290 | |
| 291 | Here is an example of how you could write a function that computes the |
| 292 | sum of the items in a list of integers; once using |
| 293 | \cfunction{PyList_GetItem()}\ttindex{PyList_GetItem()}, and once using |
| 294 | \cfunction{PySequence_GetItem()}\ttindex{PySequence_GetItem()}. |
| 295 | |
| 296 | \begin{verbatim} |
Fred Drake | 847c51a | 2001-10-25 15:53:44 +0000 | [diff] [blame] | 297 | long |
| 298 | sum_list(PyObject *list) |
Fred Drake | 3adf79e | 2001-10-12 19:01:43 +0000 | [diff] [blame] | 299 | { |
| 300 | int i, n; |
| 301 | long total = 0; |
| 302 | PyObject *item; |
| 303 | |
| 304 | n = PyList_Size(list); |
| 305 | if (n < 0) |
| 306 | return -1; /* Not a list */ |
| 307 | for (i = 0; i < n; i++) { |
| 308 | item = PyList_GetItem(list, i); /* Can't fail */ |
| 309 | if (!PyInt_Check(item)) continue; /* Skip non-integers */ |
| 310 | total += PyInt_AsLong(item); |
| 311 | } |
| 312 | return total; |
| 313 | } |
| 314 | \end{verbatim} |
| 315 | \ttindex{sum_list()} |
| 316 | |
| 317 | \begin{verbatim} |
Fred Drake | 847c51a | 2001-10-25 15:53:44 +0000 | [diff] [blame] | 318 | long |
| 319 | sum_sequence(PyObject *sequence) |
Fred Drake | 3adf79e | 2001-10-12 19:01:43 +0000 | [diff] [blame] | 320 | { |
| 321 | int i, n; |
| 322 | long total = 0; |
| 323 | PyObject *item; |
| 324 | n = PySequence_Length(sequence); |
| 325 | if (n < 0) |
| 326 | return -1; /* Has no length */ |
| 327 | for (i = 0; i < n; i++) { |
| 328 | item = PySequence_GetItem(sequence, i); |
| 329 | if (item == NULL) |
| 330 | return -1; /* Not a sequence, or other failure */ |
| 331 | if (PyInt_Check(item)) |
| 332 | total += PyInt_AsLong(item); |
| 333 | Py_DECREF(item); /* Discard reference ownership */ |
| 334 | } |
| 335 | return total; |
| 336 | } |
| 337 | \end{verbatim} |
| 338 | \ttindex{sum_sequence()} |
| 339 | |
| 340 | |
| 341 | \subsection{Types \label{types}} |
| 342 | |
| 343 | There are few other data types that play a significant role in |
| 344 | the Python/C API; most are simple C types such as \ctype{int}, |
| 345 | \ctype{long}, \ctype{double} and \ctype{char*}. A few structure types |
| 346 | are used to describe static tables used to list the functions exported |
| 347 | by a module or the data attributes of a new object type, and another |
| 348 | is used to describe the value of a complex number. These will |
| 349 | be discussed together with the functions that use them. |
| 350 | |
| 351 | |
| 352 | \section{Exceptions \label{exceptions}} |
| 353 | |
| 354 | The Python programmer only needs to deal with exceptions if specific |
| 355 | error handling is required; unhandled exceptions are automatically |
| 356 | propagated to the caller, then to the caller's caller, and so on, until |
| 357 | they reach the top-level interpreter, where they are reported to the |
| 358 | user accompanied by a stack traceback. |
| 359 | |
| 360 | For C programmers, however, error checking always has to be explicit. |
| 361 | All functions in the Python/C API can raise exceptions, unless an |
| 362 | explicit claim is made otherwise in a function's documentation. In |
| 363 | general, when a function encounters an error, it sets an exception, |
| 364 | discards any object references that it owns, and returns an |
| 365 | error indicator --- usually \NULL{} or \code{-1}. A few functions |
| 366 | return a Boolean true/false result, with false indicating an error. |
| 367 | Very few functions return no explicit error indicator or have an |
| 368 | ambiguous return value, and require explicit testing for errors with |
| 369 | \cfunction{PyErr_Occurred()}\ttindex{PyErr_Occurred()}. |
| 370 | |
| 371 | Exception state is maintained in per-thread storage (this is |
| 372 | equivalent to using global storage in an unthreaded application). A |
| 373 | thread can be in one of two states: an exception has occurred, or not. |
| 374 | The function \cfunction{PyErr_Occurred()} can be used to check for |
| 375 | this: it returns a borrowed reference to the exception type object |
| 376 | when an exception has occurred, and \NULL{} otherwise. There are a |
| 377 | number of functions to set the exception state: |
| 378 | \cfunction{PyErr_SetString()}\ttindex{PyErr_SetString()} is the most |
| 379 | common (though not the most general) function to set the exception |
| 380 | state, and \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} clears the |
| 381 | exception state. |
| 382 | |
| 383 | The full exception state consists of three objects (all of which can |
| 384 | be \NULL): the exception type, the corresponding exception |
| 385 | value, and the traceback. These have the same meanings as the Python |
| 386 | \withsubitem{(in module sys)}{ |
| 387 | \ttindex{exc_type}\ttindex{exc_value}\ttindex{exc_traceback}} |
| 388 | objects \code{sys.exc_type}, \code{sys.exc_value}, and |
| 389 | \code{sys.exc_traceback}; however, they are not the same: the Python |
| 390 | objects represent the last exception being handled by a Python |
| 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 bytecode interpreter's |
| 394 | main loop, which takes care of transferring it to \code{sys.exc_type} |
| 395 | and friends. |
| 396 | |
| 397 | Note that starting with Python 1.5, the preferred, thread-safe way to |
| 398 | access the exception state from Python code is to call the function |
| 399 | \withsubitem{(in module sys)}{\ttindex{exc_info()}} |
| 400 | \function{sys.exc_info()}, which returns the per-thread exception state |
| 401 | for Python code. Also, the semantics of both ways to access the |
| 402 | exception state have changed so that a function which catches an |
| 403 | exception will save and restore its thread's exception state so as to |
| 404 | preserve the exception state of its caller. This prevents common bugs |
| 405 | in exception handling code caused by an innocent-looking function |
| 406 | overwriting the exception being handled; it also reduces the often |
| 407 | unwanted lifetime extension for objects that are referenced by the |
| 408 | stack frames in the traceback. |
| 409 | |
| 410 | As a general principle, a function that calls another function to |
| 411 | perform some task should check whether the called function raised an |
| 412 | exception, and if so, pass the exception state on to its caller. It |
| 413 | should discard any object references that it owns, and return an |
| 414 | error indicator, but it should \emph{not} set another exception --- |
| 415 | that would overwrite the exception that was just raised, and lose |
| 416 | important information about the exact cause of the error. |
| 417 | |
| 418 | A simple example of detecting exceptions and passing them on is shown |
| 419 | in the \cfunction{sum_sequence()}\ttindex{sum_sequence()} example |
| 420 | above. It so happens that that example doesn't need to clean up any |
| 421 | owned references when it detects an error. The following example |
| 422 | function shows some error cleanup. First, to remind you why you like |
| 423 | Python, we show the equivalent Python code: |
| 424 | |
| 425 | \begin{verbatim} |
| 426 | def incr_item(dict, key): |
| 427 | try: |
| 428 | item = dict[key] |
| 429 | except KeyError: |
| 430 | item = 0 |
| 431 | dict[key] = item + 1 |
| 432 | \end{verbatim} |
| 433 | \ttindex{incr_item()} |
| 434 | |
| 435 | Here is the corresponding C code, in all its glory: |
| 436 | |
| 437 | \begin{verbatim} |
Fred Drake | 847c51a | 2001-10-25 15:53:44 +0000 | [diff] [blame] | 438 | int |
| 439 | incr_item(PyObject *dict, PyObject *key) |
Fred Drake | 3adf79e | 2001-10-12 19:01:43 +0000 | [diff] [blame] | 440 | { |
| 441 | /* Objects all initialized to NULL for Py_XDECREF */ |
| 442 | PyObject *item = NULL, *const_one = NULL, *incremented_item = NULL; |
| 443 | int rv = -1; /* Return value initialized to -1 (failure) */ |
| 444 | |
| 445 | item = PyObject_GetItem(dict, key); |
| 446 | if (item == NULL) { |
| 447 | /* Handle KeyError only: */ |
| 448 | if (!PyErr_ExceptionMatches(PyExc_KeyError)) |
| 449 | goto error; |
| 450 | |
| 451 | /* Clear the error and use zero: */ |
| 452 | PyErr_Clear(); |
| 453 | item = PyInt_FromLong(0L); |
| 454 | if (item == NULL) |
| 455 | goto error; |
| 456 | } |
| 457 | const_one = PyInt_FromLong(1L); |
| 458 | if (const_one == NULL) |
| 459 | goto error; |
| 460 | |
| 461 | incremented_item = PyNumber_Add(item, const_one); |
| 462 | if (incremented_item == NULL) |
| 463 | goto error; |
| 464 | |
| 465 | if (PyObject_SetItem(dict, key, incremented_item) < 0) |
| 466 | goto error; |
| 467 | rv = 0; /* Success */ |
| 468 | /* Continue with cleanup code */ |
| 469 | |
| 470 | error: |
| 471 | /* Cleanup code, shared by success and failure path */ |
| 472 | |
| 473 | /* Use Py_XDECREF() to ignore NULL references */ |
| 474 | Py_XDECREF(item); |
| 475 | Py_XDECREF(const_one); |
| 476 | Py_XDECREF(incremented_item); |
| 477 | |
| 478 | return rv; /* -1 for error, 0 for success */ |
| 479 | } |
| 480 | \end{verbatim} |
| 481 | \ttindex{incr_item()} |
| 482 | |
| 483 | This example represents an endorsed use of the \keyword{goto} statement |
| 484 | in C! It illustrates the use of |
| 485 | \cfunction{PyErr_ExceptionMatches()}\ttindex{PyErr_ExceptionMatches()} and |
| 486 | \cfunction{PyErr_Clear()}\ttindex{PyErr_Clear()} to |
| 487 | handle specific exceptions, and the use of |
| 488 | \cfunction{Py_XDECREF()}\ttindex{Py_XDECREF()} to |
| 489 | dispose of owned references that may be \NULL{} (note the |
| 490 | \character{X} in the name; \cfunction{Py_DECREF()} would crash when |
| 491 | confronted with a \NULL{} reference). It is important that the |
| 492 | variables used to hold owned references are initialized to \NULL{} for |
| 493 | this to work; likewise, the proposed return value is initialized to |
| 494 | \code{-1} (failure) and only set to success after the final call made |
| 495 | is successful. |
| 496 | |
| 497 | |
| 498 | \section{Embedding Python \label{embedding}} |
| 499 | |
| 500 | The one important task that only embedders (as opposed to extension |
| 501 | writers) of the Python interpreter have to worry about is the |
| 502 | initialization, and possibly the finalization, of the Python |
| 503 | interpreter. Most functionality of the interpreter can only be used |
| 504 | after the interpreter has been initialized. |
| 505 | |
| 506 | The basic initialization function is |
| 507 | \cfunction{Py_Initialize()}\ttindex{Py_Initialize()}. |
| 508 | This initializes the table of loaded modules, and creates the |
| 509 | fundamental modules \module{__builtin__}\refbimodindex{__builtin__}, |
| 510 | \module{__main__}\refbimodindex{__main__}, \module{sys}\refbimodindex{sys}, |
| 511 | and \module{exceptions}.\refbimodindex{exceptions} It also initializes |
| 512 | the module search path (\code{sys.path}).% |
| 513 | \indexiii{module}{search}{path} |
| 514 | \withsubitem{(in module sys)}{\ttindex{path}} |
| 515 | |
| 516 | \cfunction{Py_Initialize()} does not set the ``script argument list'' |
| 517 | (\code{sys.argv}). If this variable is needed by Python code that |
| 518 | will be executed later, it must be set explicitly with a call to |
| 519 | \code{PySys_SetArgv(\var{argc}, |
| 520 | \var{argv})}\ttindex{PySys_SetArgv()} subsequent to the call to |
| 521 | \cfunction{Py_Initialize()}. |
| 522 | |
| 523 | On most systems (in particular, on \UNIX{} and Windows, although the |
| 524 | details are slightly different), |
| 525 | \cfunction{Py_Initialize()} calculates the module search path based |
| 526 | upon its best guess for the location of the standard Python |
| 527 | interpreter executable, assuming that the Python library is found in a |
| 528 | fixed location relative to the Python interpreter executable. In |
| 529 | particular, it looks for a directory named |
| 530 | \file{lib/python\shortversion} relative to the parent directory where |
| 531 | the executable named \file{python} is found on the shell command |
| 532 | search path (the environment variable \envvar{PATH}). |
| 533 | |
| 534 | For instance, if the Python executable is found in |
| 535 | \file{/usr/local/bin/python}, it will assume that the libraries are in |
| 536 | \file{/usr/local/lib/python\shortversion}. (In fact, this particular path |
| 537 | is also the ``fallback'' location, used when no executable file named |
| 538 | \file{python} is found along \envvar{PATH}.) The user can override |
| 539 | this behavior by setting the environment variable \envvar{PYTHONHOME}, |
| 540 | or insert additional directories in front of the standard path by |
| 541 | setting \envvar{PYTHONPATH}. |
| 542 | |
| 543 | The embedding application can steer the search by calling |
| 544 | \code{Py_SetProgramName(\var{file})}\ttindex{Py_SetProgramName()} \emph{before} calling |
| 545 | \cfunction{Py_Initialize()}. Note that \envvar{PYTHONHOME} still |
| 546 | overrides this and \envvar{PYTHONPATH} is still inserted in front of |
| 547 | the standard path. An application that requires total control has to |
| 548 | provide its own implementation of |
| 549 | \cfunction{Py_GetPath()}\ttindex{Py_GetPath()}, |
| 550 | \cfunction{Py_GetPrefix()}\ttindex{Py_GetPrefix()}, |
| 551 | \cfunction{Py_GetExecPrefix()}\ttindex{Py_GetExecPrefix()}, and |
| 552 | \cfunction{Py_GetProgramFullPath()}\ttindex{Py_GetProgramFullPath()} (all |
| 553 | defined in \file{Modules/getpath.c}). |
| 554 | |
| 555 | Sometimes, it is desirable to ``uninitialize'' Python. For instance, |
| 556 | the application may want to start over (make another call to |
| 557 | \cfunction{Py_Initialize()}) or the application is simply done with its |
| 558 | use of Python and wants to free all memory allocated by Python. This |
| 559 | can be accomplished by calling \cfunction{Py_Finalize()}. The function |
| 560 | \cfunction{Py_IsInitialized()}\ttindex{Py_IsInitialized()} returns |
| 561 | true if Python is currently in the initialized state. More |
| 562 | information about these functions is given in a later chapter. |