1 |
/* |
/* |
2 |
$Id$ |
$Id$ |
3 |
|
|
4 |
Copyright (C) 2003/2004 Alexandre Courbot <alexandrecourbot@linuxgames.com> |
Copyright (C) 2003/2004 Alexandre Courbot <alexandrecourbot@linuxgames.com> |
5 |
Part of the Adonthell Project http://adonthell.linuxgames.com |
Part of the Adonthell Project http://adonthell.linuxgames.com |
6 |
|
|
7 |
Adonthell is free software; you can redistribute it and/or modify |
Adonthell is free software; you can redistribute it and/or modify |
8 |
it under the terms of the GNU General Public License as published by |
it under the terms of the GNU General Public License as published by |
9 |
the Free Software Foundation; either version 2 of the License, or |
the Free Software Foundation; either version 2 of the License, or |
10 |
(at your option) any later version. |
(at your option) any later version. |
11 |
|
|
12 |
Adonthell is distributed in the hope that it will be useful, |
Adonthell is distributed in the hope that it will be useful, |
13 |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
but WITHOUT ANY WARRANTY; without even the implied warranty of |
14 |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |
15 |
GNU General Public License for more details. |
GNU General Public License for more details. |
16 |
|
|
17 |
You should have received a copy of the GNU General Public License |
You should have received a copy of the GNU General Public License |
18 |
along with Adonthell; if not, write to the Free Software |
along with Adonthell; if not, write to the Free Software |
19 |
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA |
20 |
*/ |
*/ |
21 |
|
|
22 |
|
|
23 |
/** |
/** |
24 |
* @file python.h |
* @file python.h |
25 |
* @author Alexandre Courbot <alexandrecourbot@linuxgames.com> |
* @author Alexandre Courbot <alexandrecourbot@linuxgames.com> |
26 |
* |
* |
27 |
* @brief The python module main include file. |
* @brief The python module main include file. |
28 |
* |
* |
29 |
* |
* |
30 |
*/ |
*/ |
31 |
|
|
32 |
#ifndef PYTHON_PYTHON_H_ |
#ifndef PYTHON_PYTHON_H_ |
33 |
#define PYTHON_PYTHON_H_ |
#define PYTHON_PYTHON_H_ |
34 |
|
|
35 |
#include <Python.h> |
#include <Python.h> |
36 |
#include "base/flat.h" |
#include "base/flat.h" |
37 |
|
|
38 |
struct swig_type_info; |
struct swig_type_info; |
39 |
extern "C" { |
extern "C" { |
40 |
swig_type_info *SWIG_Python_TypeQuery (const char*); |
swig_type_info *SWIG_Python_TypeQuery (const char*); |
41 |
int SWIG_Python_ConvertPtr (PyObject*, void**, swig_type_info*, int); |
int SWIG_Python_ConvertPtr (PyObject*, void**, swig_type_info*, int); |
42 |
PyObject *SWIG_Python_NewPointerObj (void*, swig_type_info*, int); |
PyObject *SWIG_Python_NewPointerObj (void*, swig_type_info*, int); |
43 |
} |
} |
44 |
|
|
45 |
/** |
/** |
46 |
* Provides a bridge between C++ and Python, |
* Provides a bridge between C++ and Python, |
47 |
* as well as some convenience classes to ease |
* as well as some convenience classes to ease |
48 |
* the use of the Adonthell library from Python. |
* the use of the Adonthell library from Python. |
49 |
* |
* |
50 |
*/ |
*/ |
51 |
namespace python |
namespace python |
52 |
{ |
{ |
53 |
/** |
/** |
54 |
* Dump any error information to stderr. |
* Dump any error information to stderr. |
55 |
* |
* |
56 |
* This function should be called after every operation |
* This function should be called after every operation |
57 |
* involving Python from C++, so the user can get informed if |
* involving Python from C++, so the user can get informed if |
58 |
* something went wrong. By default, all the methods of this |
* something went wrong. By default, all the methods of this |
59 |
* module call it when appropriate. |
* module call it when appropriate. |
60 |
* |
* |
61 |
*/ |
*/ |
62 |
void show_traceback(); |
void show_traceback(); |
63 |
|
|
64 |
/** |
/** |
65 |
* @name Initialization and cleanup. |
* @name Initialization and cleanup. |
66 |
* |
* |
67 |
*/ |
*/ |
68 |
//@{ |
//@{ |
69 |
|
/** |
70 |
void init(); |
* Initialize the embedded Python interpreter. |
71 |
void cleanup(); |
*/ |
72 |
|
void init(); |
73 |
//@} |
|
74 |
|
/** |
75 |
/** |
* Shutdown the embedded Python interpreter. |
76 |
* @name High-level functions. |
*/ |
77 |
* |
void cleanup(); |
78 |
*/ |
//@} |
79 |
//@{ |
|
80 |
/** |
/** |
81 |
* Add given path to Python's list of module directories. |
* @name High-level functions. |
82 |
* @param path the path to add. |
* |
83 |
* @return \b true on success, \b false otherwise. |
*/ |
84 |
*/ |
//@{ |
85 |
bool add_search_path(const std::string & path); |
/** |
86 |
|
* Add given path to Python's list of module directories. |
87 |
/** |
* @param path the path to add. |
88 |
* Execute a python statement and return resulting object. |
* @return \b true on success, \b false otherwise. |
89 |
* This is a new reference that needs to be Py_DECREF'd when done. |
*/ |
90 |
* @param statement Python code to execute. |
bool add_search_path(const std::string & path); |
91 |
* @param one of Py_eval_input, Py_file_input or Py_single_input |
|
92 |
* @return \b result on success, \b NULL otherwise. |
/** |
93 |
*/ |
* Execute a python statement and return resulting object. |
94 |
PyObject* run_string (const std::string & statement, const int & start = Py_eval_input); |
* This is a new reference that needs to be Py_DECREF'd when done. |
95 |
|
* @param statement Python code to execute. |
96 |
/** |
* @param start one of Py_eval_input, Py_file_input or Py_single_input |
97 |
* Execute a python statement and return success. |
* @return \b result on success, \b NULL otherwise. |
98 |
* @param statement Python code to execute. |
*/ |
99 |
* @return \b true on success, \b false otherwise. |
PyObject* run_string (const std::string & statement, const int & start = Py_eval_input); |
100 |
*/ |
|
101 |
bool run_simple_string (const std::string & statement); |
/** |
102 |
|
* Execute a python statement and return success. |
103 |
PyObject * import_module(const std::string & name); |
* @param statement Python code to execute. |
104 |
|
* @return \b true on success, \b false otherwise. |
105 |
//@} |
*/ |
106 |
|
bool run_simple_string (const std::string & statement); |
107 |
/** |
|
108 |
* @name C++ to Python instance passing functions. |
/** |
109 |
* |
* Import %python module with given name. |
110 |
*/ |
* @param name name of module to import |
111 |
//@{ |
* @return imported module or \c NULL on error. |
112 |
|
*/ |
113 |
/** |
PyObject * import_module(const std::string & name); |
114 |
* Ownership of a python object made with pass_instance. Value |
|
115 |
* python::c_owns means that once the Python object is deleted, the |
//@} |
116 |
* C++ instance will remain valid. On the contrary, python::python_owns |
|
117 |
* will cause the C++ instance to be destroyed when the Python object is |
/** |
118 |
* deleted. |
* @name C++ to Python instance passing functions. |
119 |
* |
* |
120 |
*/ |
*/ |
121 |
typedef enum { c_owns = 0, python_owns = 1 } ownership; |
//@{ |
122 |
|
|
123 |
/** |
/** |
124 |
* Default version of pass_instance - it will fetch the name of the class |
* Ownership of a python object made with pass_instance. Value |
125 |
* that is passed using a specialized version of get_type_name to create |
* python::c_owns means that once the Python object is deleted, the |
126 |
* a Python object from a pointer. |
* C++ instance will remain valid. On the contrary, python::python_owns |
127 |
* |
* will cause the C++ instance to be destroyed when the Python object is |
128 |
* @param arg a pointer to the object to pass to Python. |
* deleted. |
129 |
* @param own ownership of the C++ object. |
* |
130 |
* |
*/ |
131 |
* @return a Python object representing \e arg. |
typedef enum { c_owns = 0, python_owns = 1 } ownership; |
132 |
*/ |
|
133 |
template <class A> inline |
/** |
134 |
PyObject * pass_instance(A arg, const ownership own = c_owns) |
* Default version of pass_instance - it will fetch the name of the class |
135 |
{ |
* that is passed using a specialized version of get_type_name to create |
136 |
swig_type_info * tt = SWIG_Python_TypeQuery (arg->get_type_name ()); |
* a Python object from a pointer. |
137 |
if (tt) return SWIG_Python_NewPointerObj(arg, tt, own); |
* |
138 |
|
* @param arg a pointer to the object to pass to Python. |
139 |
fprintf (stderr, "*** pass_instance: type '%s' unknown to SWIG\n", arg->get_type_name ()); |
* @param own ownership of the C++ object. |
140 |
return NULL; |
* |
141 |
} |
* @return a Python object representing \e arg. |
142 |
|
*/ |
143 |
/** |
template <class A> inline |
144 |
* Specialized version of pass_instance which makes a Python integer |
PyObject * pass_instance(A arg, const ownership own = c_owns) |
145 |
* from a C++ one. |
{ |
146 |
* |
swig_type_info * tt = SWIG_Python_TypeQuery (arg->get_type_name ()); |
147 |
* @param arg the integer to be passed to Python. |
if (tt) return SWIG_Python_NewPointerObj(arg, tt, own); |
148 |
* @param own useless here. |
|
149 |
* |
fprintf (stderr, "*** pass_instance: type '%s' unknown to SWIG\n", arg->get_type_name ()); |
150 |
* @return a Python object representing \e arg. |
return NULL; |
151 |
*/ |
} |
152 |
template <> inline |
|
153 |
PyObject * pass_instance<int>(int arg, const ownership own) |
/** |
154 |
{ |
* Specialized version of pass_instance which makes a Python integer |
155 |
return PyInt_FromLong(arg); |
* from a C++ one. |
156 |
show_traceback(); |
* |
157 |
} |
* @param arg the integer to be passed to Python. |
158 |
|
* @param own useless here. |
159 |
/** |
* |
160 |
* Specialized version of pass_instance which makes a Python boolean |
* @return a Python object representing \e arg. |
161 |
* from a C++ one. |
*/ |
162 |
* |
template <> inline |
163 |
* @param arg the boolean to be passed to Python. |
PyObject * pass_instance<int>(int arg, const ownership own) |
164 |
* @param own useless here. |
{ |
165 |
* |
return PyInt_FromLong(arg); |
166 |
* @return a Python object representing \e arg. |
show_traceback(); |
167 |
*/ |
} |
168 |
template <> inline |
|
169 |
PyObject * pass_instance<bool>(bool arg, const ownership own) |
/** |
170 |
{ |
* Specialized version of pass_instance which makes a Python boolean |
171 |
return PyInt_FromLong((int)arg); |
* from a C++ one. |
172 |
show_traceback(); |
* |
173 |
} |
* @param arg the boolean to be passed to Python. |
174 |
|
* @param own useless here. |
175 |
/** |
* |
176 |
* Specialized version of pass_instance which makes a Python string |
* @return a Python object representing \e arg. |
177 |
* from a C++ std::string. |
*/ |
178 |
* |
template <> inline |
179 |
* @param arg the std::string to be passed to Python. |
PyObject * pass_instance<bool>(bool arg, const ownership own) |
180 |
* @param own useless here. |
{ |
181 |
* |
return PyInt_FromLong((int)arg); |
182 |
* @return a Python object representing \e arg. |
show_traceback(); |
183 |
*/ |
} |
184 |
template <> inline |
|
185 |
PyObject * pass_instance<std::string &>(std::string & arg, const ownership own) |
/** |
186 |
{ |
* Specialized version of pass_instance which makes a Python string |
187 |
return PyString_FromString(arg.c_str()); |
* from a C++ std::string. |
188 |
show_traceback(); |
* |
189 |
} |
* @param arg the std::string to be passed to Python. |
190 |
|
* @param own useless here. |
191 |
/** |
* |
192 |
* Specialized version of pass_instance which makes a Python string |
* @return a Python object representing \e arg. |
193 |
* from a C++ char *. |
*/ |
194 |
* |
template <> inline |
195 |
* @param arg the char * to be passed to Python. |
PyObject * pass_instance<std::string &>(std::string & arg, const ownership own) |
196 |
* @param own useless here. |
{ |
197 |
* |
return PyString_FromString(arg.c_str()); |
198 |
* @return a Python object representing \e arg. |
show_traceback(); |
199 |
*/ |
} |
200 |
template <> inline |
|
201 |
PyObject * pass_instance<const char *>(const char * arg, const ownership own) |
/** |
202 |
{ |
* Specialized version of pass_instance which makes a Python string |
203 |
return PyString_FromString((char *) arg); |
* from a C++ char *. |
204 |
show_traceback(); |
* |
205 |
} |
* @param arg the char * to be passed to Python. |
206 |
|
* @param own useless here. |
207 |
/** |
* |
208 |
* Sets the ownership of an object created with pass_instance. |
* @return a Python object representing \e arg. |
209 |
* |
*/ |
210 |
* @param obj the object to change ownership of. |
template <> inline |
211 |
* @param o the new ownership. |
PyObject * pass_instance<const char *>(const char * arg, const ownership own) |
212 |
*/ |
{ |
213 |
inline void set_ownership(PyObject * obj, const ownership o) |
return PyString_FromString((char *) arg); |
214 |
{ |
show_traceback(); |
215 |
PyObject * n = PyInt_FromLong(o); |
} |
216 |
PyObject_SetAttrString (obj, (char*)"thisown", n); |
|
217 |
Py_DECREF(n); |
/** |
218 |
show_traceback(); |
* Sets the ownership of an object created with pass_instance. |
219 |
} |
* |
220 |
|
* @param obj the object to change ownership of. |
221 |
//@} |
* @param o the new ownership. |
222 |
|
*/ |
223 |
/** |
inline void set_ownership(PyObject * obj, const ownership o) |
224 |
* @name Python to C++ instance passing functions. |
{ |
225 |
* |
PyObject * n = PyInt_FromLong(o); |
226 |
*/ |
PyObject_SetAttrString (obj, (char*)"thisown", n); |
227 |
//@{ |
Py_DECREF(n); |
228 |
|
show_traceback(); |
229 |
/** |
} |
230 |
* Retrieves the C++ intance of a Python object created with pass_instance. |
|
231 |
* |
//@} |
232 |
* This is the default version of retrieve_instance. The template element A must |
|
233 |
* be a pointer type. |
/** |
234 |
* |
* @name Python to C++ instance passing functions. |
235 |
* @param pyinstance The Python instance of the object to retrieve. |
* |
236 |
* |
*/ |
237 |
* @return A borrowed pointer to the C++ instance of the object. |
//@{ |
238 |
*/ |
|
239 |
template <class A, class B> inline |
/** |
240 |
A retrieve_instance(PyObject * pyinstance) |
* Retrieves the C++ intance of a Python object created with pass_instance. |
241 |
{ |
* |
242 |
B *retvalue = NULL; |
* This is the default version of retrieve_instance. The template element A must |
243 |
|
* be a pointer type. |
244 |
swig_type_info * tt = SWIG_Python_TypeQuery (B::get_type_name_s ()); |
* |
245 |
if (!tt) return NULL; |
* @param pyinstance The Python instance of the object to retrieve. |
246 |
if (SWIG_Python_ConvertPtr(pyinstance, (void **) &retvalue, tt, 0) == -1) return NULL; |
* |
247 |
return retvalue; |
* @return A borrowed pointer to the C++ instance of the object. |
248 |
} |
*/ |
249 |
|
template <class A, class B> inline |
250 |
/** |
A retrieve_instance(PyObject * pyinstance) |
251 |
* Retrieves the C++ value of a Python integer. |
{ |
252 |
* |
B *retvalue = NULL; |
253 |
* @param pyinstance The Python integer to retrieve. |
|
254 |
* |
swig_type_info * tt = SWIG_Python_TypeQuery (B::get_type_name_s ()); |
255 |
* @return C++ value of pyinstance. |
if (!tt) return NULL; |
256 |
*/ |
if (SWIG_Python_ConvertPtr(pyinstance, (void **) &retvalue, tt, 0) == -1) return NULL; |
257 |
template <> inline |
return retvalue; |
258 |
int retrieve_instance<int, int>(PyObject * pyinstance) |
} |
259 |
{ |
|
260 |
return PyInt_AsLong(pyinstance); |
/** |
261 |
show_traceback(); |
* Retrieves the C++ value of a Python integer. |
262 |
} |
* |
263 |
|
* @param pyinstance The Python integer to retrieve. |
264 |
/** |
* |
265 |
* Retrieves the C++ value of a Python boolean. |
* @return C++ value of pyinstance. |
266 |
* |
*/ |
267 |
* @param pyinstance The Python boolean to retrieve. |
template <> inline |
268 |
* |
int retrieve_instance<int, int>(PyObject * pyinstance) |
269 |
* @return C++ value of pyinstance. |
{ |
270 |
*/ |
return PyInt_AsLong(pyinstance); |
271 |
template <> inline |
show_traceback(); |
272 |
bool retrieve_instance<bool, bool>(PyObject * pyinstance) |
} |
273 |
{ |
|
274 |
return (bool)PyInt_AsLong(pyinstance); |
/** |
275 |
show_traceback(); |
* Retrieves the C++ value of a Python boolean. |
276 |
} |
* |
277 |
|
* @param pyinstance The Python boolean to retrieve. |
278 |
/** |
* |
279 |
* Retrieves the C++ value of a Python string as a char *. |
* @return C++ value of pyinstance. |
280 |
* |
*/ |
281 |
* @param pyinstance The Python string to retrieve. |
template <> inline |
282 |
* |
bool retrieve_instance<bool, bool>(PyObject * pyinstance) |
283 |
* @return char * string value of pyinstance. |
{ |
284 |
*/ |
return (bool)PyInt_AsLong(pyinstance); |
285 |
template <> inline |
show_traceback(); |
286 |
const char * retrieve_instance<const char *, const char *>(PyObject * pyinstance) |
} |
287 |
{ |
|
288 |
return PyString_AsString(pyinstance); |
/** |
289 |
show_traceback(); |
* Retrieves the C++ value of a Python string as a char *. |
290 |
} |
* |
291 |
|
* @param pyinstance The Python string to retrieve. |
292 |
/** |
* |
293 |
* Retrieves the C++ value of a Python string as a std::string. |
* @return char * string value of pyinstance. |
294 |
* |
*/ |
295 |
* @param pyinstance The Python string to retrieve. |
template <> inline |
296 |
* |
const char * retrieve_instance<const char *, const char *>(PyObject * pyinstance) |
297 |
* @return std::string value of pyinstance. |
{ |
298 |
*/ |
return PyString_AsString(pyinstance); |
299 |
template <> inline |
show_traceback(); |
300 |
std::string retrieve_instance<std::string, std::string>(PyObject * pyinstance) |
} |
301 |
{ |
|
302 |
return std::string(PyString_AsString(pyinstance)); |
/** |
303 |
show_traceback(); |
* Retrieves the C++ value of a Python string as a std::string. |
304 |
} |
* |
305 |
//@} |
* @param pyinstance The Python string to retrieve. |
306 |
|
* |
307 |
/** |
* @return std::string value of pyinstance. |
308 |
* @name Loading / Saving |
*/ |
309 |
*/ |
template <> inline |
310 |
//@{ |
std::string retrieve_instance<std::string, std::string>(PyObject * pyinstance) |
311 |
/** |
{ |
312 |
* Read the contents of a tuple from given stream. |
return std::string(PyString_AsString(pyinstance)); |
313 |
* @param out flattener to read the tuple from. |
show_traceback(); |
314 |
* @param start index from where to start filling the tuple. |
} |
315 |
* @return a new tuple filled with the data read from stream. |
//@} |
316 |
*/ |
|
317 |
PyObject *get_tuple (base::flat & in, u_int16 start = 0); |
/** |
318 |
|
* @name Loading / Saving |
319 |
/** |
*/ |
320 |
* Write the contents of a tuple to given stream. Only supports integer and |
//@{ |
321 |
* string objects. |
/** |
322 |
* @param tuple Python tuple whose contents to save. |
* Read the contents of a tuple from given stream. |
323 |
* @param in flattener to store the tuple in. |
* @param in flattener to read the tuple from. |
324 |
* @param start index from where to start flattening the tuple. |
* @param start index from where to start filling the tuple. |
325 |
*/ |
* @return a new tuple filled with the data read from stream. |
326 |
void put_tuple (PyObject *tuple, base::flat & out, u_int16 start = 0); |
*/ |
327 |
//@} |
PyObject *get_tuple (base::flat & in, u_int16 start = 0); |
328 |
} |
|
329 |
|
/** |
330 |
#include "python/callback.h" |
* Write the contents of a tuple to given stream. Only supports integer and |
331 |
|
* string objects. |
332 |
#endif |
* @param tuple Python tuple whose contents to save. |
333 |
|
* @param out flattener to store the tuple in. |
334 |
|
* @param start index from where to start flattening the tuple. |
335 |
|
*/ |
336 |
|
void put_tuple (PyObject *tuple, base::flat & out, u_int16 start = 0); |
337 |
|
//@} |
338 |
|
} |
339 |
|
|
340 |
|
#include "python/callback.h" |
341 |
|
|
342 |
|
#endif |