cpython-lru_cache-weakref: Doc/ext/embedding.tex annotate

annotate Doc/ext/embedding.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	bc02c3b09626
children	1a2b5344d1cc 4f063b80308d

rev	line source
19402 554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	1 \chapter{Embedding Python in Another Application
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	2 \label{embedding}}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	3
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	4 The previous chapters discussed how to extend Python, that is, how to
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	5 extend the functionality of Python by attaching a library of C
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	6 functions to it. It is also possible to do it the other way around:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	7 enrich your C/\Cpp{} application by embedding Python in it. Embedding
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	8 provides your application with the ability to implement some of the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	9 functionality of your application in Python rather than C or \Cpp.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	10 This can be used for many purposes; one example would be to allow
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	11 users to tailor the application to their needs by writing some scripts
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	12 in Python. You can also use it yourself if some of the functionality
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	13 can be written in Python more easily.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	14
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	15 Embedding Python is similar to extending it, but not quite. The
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	16 difference is that when you extend Python, the main program of the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	17 application is still the Python interpreter, while if you embed
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	18 Python, the main program may have nothing to do with Python ---
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	19 instead, some parts of the application occasionally call the Python
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	20 interpreter to run some Python code.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	21
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	22 So if you are embedding Python, you are providing your own main
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	23 program. One of the things this main program has to do is initialize
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	24 the Python interpreter. At the very least, you have to call the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	25 function \cfunction{Py_Initialize()} (on Mac OS, call
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	26 \cfunction{PyMac_Initialize()} instead). There are optional calls to
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	27 pass command line arguments to Python. Then later you can call the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	28 interpreter from any part of the application.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	29
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	30 There are several different ways to call the interpreter: you can pass
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	31 a string containing Python statements to
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	32 \cfunction{PyRun_SimpleString()}, or you can pass a stdio file pointer
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	33 and a file name (for identification in error messages only) to
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	34 \cfunction{PyRun_SimpleFile()}. You can also call the lower-level
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	35 operations described in the previous chapters to construct and use
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	36 Python objects.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	37
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	38 A simple demo of embedding Python can be found in the directory
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	39 \file{Demo/embed/} of the source distribution.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	40
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	41
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	42 \begin{seealso}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	43 \seetitle[../api/api.html]{Python/C API Reference Manual}{The
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	44 details of Python's C interface are given in this manual.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	45 A great deal of necessary information can be found here.}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	46 \end{seealso}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	47
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	48
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	49 \section{Very High Level Embedding
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	50 \label{high-level-embedding}}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	51
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	52 The simplest form of embedding Python is the use of the very
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	53 high level interface. This interface is intended to execute a
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	54 Python script without needing to interact with the application
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	55 directly. This can for example be used to perform some operation
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	56 on a file.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	57
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	58 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	59 #include <Python.h>
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	60
19769 a5eaef47a9b3 Use the standard argument convention for main(), and conform to the Fred Drake <fdrake@acm.org> parents: 19402 diff changeset	61 int
a5eaef47a9b3 Use the standard argument convention for main(), and conform to the Fred Drake <fdrake@acm.org> parents: 19402 diff changeset	62 main(int argc, char *argv[])
19402 554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	63 {
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	64 Py_Initialize();
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	65 PyRun_SimpleString("from time import time,ctime\n"
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	66 "print 'Today is',ctime(time())\n");
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	67 Py_Finalize();
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	68 return 0;
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	69 }
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	70 \end{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	71
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	72 The above code first initializes the Python interpreter with
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	73 \cfunction{Py_Initialize()}, followed by the execution of a hard-coded
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	74 Python script that print the date and time. Afterwards, the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	75 \cfunction{Py_Finalize()} call shuts the interpreter down, followed by
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	76 the end of the program. In a real program, you may want to get the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	77 Python script from another source, perhaps a text-editor routine, a
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	78 file, or a database. Getting the Python code from a file can better
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	79 be done by using the \cfunction{PyRun_SimpleFile()} function, which
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	80 saves you the trouble of allocating memory space and loading the file
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	81 contents.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	82
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	83
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	84 \section{Beyond Very High Level Embedding: An overview
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	85 \label{lower-level-embedding}}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	86
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	87 The high level interface gives you the ability to execute
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	88 arbitrary pieces of Python code from your application, but
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	89 exchanging data values is quite cumbersome to say the least. If
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	90 you want that, you should use lower level calls. At the cost of
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	91 having to write more C code, you can achieve almost anything.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	92
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	93 It should be noted that extending Python and embedding Python
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	94 is quite the same activity, despite the different intent. Most
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	95 topics discussed in the previous chapters are still valid. To
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	96 show this, consider what the extension code from Python to C
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	97 really does:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	98
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	99 \begin{enumerate}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	100 \item Convert data values from Python to C,
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	101 \item Perform a function call to a C routine using the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	102 converted values, and
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	103 \item Convert the data values from the call from C to Python.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	104 \end{enumerate}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	105
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	106 When embedding Python, the interface code does:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	107
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	108 \begin{enumerate}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	109 \item Convert data values from C to Python,
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	110 \item Perform a function call to a Python interface routine
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	111 using the converted values, and
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	112 \item Convert the data values from the call from Python to C.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	113 \end{enumerate}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	114
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	115 As you can see, the data conversion steps are simply swapped to
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	116 accomodate the different direction of the cross-language transfer.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	117 The only difference is the routine that you call between both
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	118 data conversions. When extending, you call a C routine, when
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	119 embedding, you call a Python routine.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	120
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	121 This chapter will not discuss how to convert data from Python
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	122 to C and vice versa. Also, proper use of references and dealing
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	123 with errors is assumed to be understood. Since these aspects do not
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	124 differ from extending the interpreter, you can refer to earlier
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	125 chapters for the required information.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	126
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	127
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	128 \section{Pure Embedding
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	129 \label{pure-embedding}}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	130
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	131 The first program aims to execute a function in a Python
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	132 script. Like in the section about the very high level interface,
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	133 the Python interpreter does not directly interact with the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	134 application (but that will change in th next section).
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	135
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	136 The code to run a function defined in a Python script is:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	137
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	138 \verbatiminput{run-func.c}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	139
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	140 This code loads a Python script using \code{argv[1]}, and calls the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	141 function named in \code{argv[2]}. Its integer arguments are the other
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	142 values of the \code{argv} array. If you compile and link this
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	143 program (let's call the finished executable \program{call}), and use
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	144 it to execute a Python script, such as:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	145
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	146 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	147 def multiply(a,b):
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	148 print "Thy shall add", a, "times", b
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	149 c = 0
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	150 for i in range(0, a):
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	151 c = c + b
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	152 return c
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	153 \end{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	154
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	155 then the result should be:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	156
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	157 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	158 $ call multiply 3 2
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	159 Thy shall add 3 times 2
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	160 Result of call: 6
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	161 \end{verbatim} % $
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	162
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	163 Although the program is quite large for its functionality, most of the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	164 code is for data conversion between Python and C, and for error
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	165 reporting. The interesting part with respect to embedding Python
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	166 starts with
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	167
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	168 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	169 Py_Initialize();
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	170 pName = PyString_FromString(argv[1]);
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	171 /* Error checking of pName left out */
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	172 pModule = PyImport_Import(pName);
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	173 \end{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	174
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	175 After initializing the interpreter, the script is loaded using
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	176 \cfunction{PyImport_Import()}. This routine needs a Python string
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	177 as its argument, which is constructed using the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	178 \cfunction{PyString_FromString()} data conversion routine.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	179
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	180 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	181 pDict = PyModule_GetDict(pModule);
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	182 /* pDict is a borrowed reference */
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	183
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	184 pFunc = PyDict_GetItemString(pDict, argv[2]);
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	185 /* pFun is a borrowed reference */
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	186
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	187 if (pFunc && PyCallable_Check(pFunc)) {
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	188 ...
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	189 }
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	190 \end{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	191
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	192 Once the script is loaded, its dictionary is retrieved with
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	193 \cfunction{PyModule_GetDict()}. The dictionary is then searched using
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	194 the normal dictionary access routines for the function name. If the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	195 name exists, and the object retunred is callable, you can safely
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	196 assume that it is a function. The program then proceeds by
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	197 constructing a tuple of arguments as normal. The call to the python
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	198 function is then made with:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	199
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	200 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	201 pValue = PyObject_CallObject(pFunc, pArgs);
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	202 \end{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	203
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	204 Upon return of the function, \code{pValue} is either \NULL{} or it
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	205 contains a reference to the return value of the function. Be sure to
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	206 release the reference after examining the value.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	207
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	208
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	209 \section{Extending Embedded Python
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	210 \label{extending-with-embedding}}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	211
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	212 Until now, the embedded Python interpreter had no access to
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	213 functionality from the application itself. The Python API allows this
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	214 by extending the embedded interpreter. That is, the embedded
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	215 interpreter gets extended with routines provided by the application.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	216 While it sounds complex, it is not so bad. Simply forget for a while
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	217 that the application starts the Python interpreter. Instead, consider
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	218 the application to be a set of subroutines, and write some glue code
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	219 that gives Python access to those routines, just like you would write
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	220 a normal Python extension. For example:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	221
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	222 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	223 static int numargs=0;
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	224
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	225 /* Return the number of arguments of the application command line */
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	226 static PyObject*
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	227 emb_numargs(PyObject self, PyObject args)
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	228 {
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	229 if(!PyArg_ParseTuple(args, ":numargs"))
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	230 return NULL;
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	231 return Py_BuildValue("i", numargs);
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	232 }
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	233
21008 61a2df56746e Exhibit good form in C code: always provide docstrings in method tables, and Fred Drake <fdrake@acm.org> parents: 19769 diff changeset	234 static PyMethodDef EmbMethods[] = {
61a2df56746e Exhibit good form in C code: always provide docstrings in method tables, and Fred Drake <fdrake@acm.org> parents: 19769 diff changeset	235 {"numargs", emb_numargs, METH_VARARGS,
61a2df56746e Exhibit good form in C code: always provide docstrings in method tables, and Fred Drake <fdrake@acm.org> parents: 19769 diff changeset	236 "Return the number of arguments received by the process."},
61a2df56746e Exhibit good form in C code: always provide docstrings in method tables, and Fred Drake <fdrake@acm.org> parents: 19769 diff changeset	237 {NULL, NULL, 0, NULL}
19402 554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	238 };
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	239 \end{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	240
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	241 Insert the above code just above the \cfunction{main()} function.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	242 Also, insert the following two statements directly after
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	243 \cfunction{Py_Initialize()}:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	244
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	245 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	246 numargs = argc;
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	247 Py_InitModule("emb", EmbMethods);
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	248 \end{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	249
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	250 These two lines initialize the \code{numargs} variable, and make the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	251 \function{emb.numargs()} function accessible to the embedded Python
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	252 interpreter. With these extensions, the Python script can do things
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	253 like
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	254
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	255 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	256 import emb
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	257 print "Number of arguments", emb.numargs()
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	258 \end{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	259
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	260 In a real application, the methods will expose an API of the
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	261 application to Python.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	262
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	263
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	264 %\section{For the future}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	265 %
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	266 %You don't happen to have a nice library to get textual
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	267 %equivalents of numeric values do you :-) ?
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	268 %Callbacks here ? (I may be using information from that section
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	269 %?!)
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	270 %threads
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	271 %code examples do not really behave well if errors happen
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	272 % (what to watch out for)
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	273
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	274
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 21008 diff changeset	275 \section{Embedding Python in \Cpp
19402 554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	276 \label{embeddingInCplusplus}}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	277
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	278 It is also possible to embed Python in a \Cpp{} program; precisely how this
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	279 is done will depend on the details of the \Cpp{} system used; in general you
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 21008 diff changeset	280 will need to write the main program in \Cpp, and use the \Cpp{} compiler
19402 554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	281 to compile and link your program. There is no need to recompile Python
21062 bc02c3b09626 Clean up some markup cruft. A number of the macros that take no Fred Drake <fdrake@acm.org> parents: 21008 diff changeset	282 itself using \Cpp.
19402 554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	283
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	284
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	285 \section{Linking Requirements
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	286 \label{link-reqs}}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	287
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	288 While the \program{configure} script shipped with the Python sources
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	289 will correctly build Python to export the symbols needed by
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	290 dynamically linked extensions, this is not automatically inherited by
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	291 applications which embed the Python library statically, at least on
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	292 \UNIX. This is an issue when the application is linked to the static
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	293 runtime library (\file{libpython.a}) and needs to load dynamic
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	294 extensions (implemented as \file{.so} files).
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	295
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	296 The problem is that some entry points are defined by the Python
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	297 runtime solely for extension modules to use. If the embedding
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	298 application does not use any of these entry points, some linkers will
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	299 not include those entries in the symbol table of the finished
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	300 executable. Some additional options are needed to inform the linker
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	301 not to remove these symbols.
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	302
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	303 Determining the right options to use for any given platform can be
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	304 quite difficult, but fortunately the Python configuration already has
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	305 those values. To retrieve them from an installed Python interpreter,
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	306 start an interactive interpreter and have a short session like this:
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	307
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	308 \begin{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	309 >>> import distutils.sysconfig
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	310 >>> distutils.sysconfig.get_config_var('LINKFORSHARED')
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	311 '-Xlinker -export-dynamic'
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	312 \end{verbatim}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	313 \refstmodindex{distutils.sysconfig}
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	314
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	315 The contents of the string presented will be the options that should
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	316 be used. If the string is empty, there's no need to add any
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	317 additional options. The \constant{LINKFORSHARED} definition
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	318 corresponds to the variable of the same name in Python's top-level
554450409a73 Split "Extending & Embedding" into separate files, one per chapter. Fred Drake <fdrake@acm.org> parents: diff changeset	319 \file{Makefile}.

Mercurial > cpython-lru_cache-weakref

annotate Doc/ext/embedding.tex @ 21467:4e35fa5d5708 legacy-trunk