boost/python
2
0
Fork 0
mirror of https://github.com/boostorg/python.git synced 2026-01-26 06:42:27 +00:00
Code Issues Projects Releases Wiki Activity

no message

Browse Source 
[SVN r20266]
This commit is contained in:
Bruno da Silva de Oliveira
2003-10-06 19:10:50 +00:00
parent 1a51a7df9e
commit 3533bd0504
33 changed files with 561 additions and 122 deletions
Download Patch File Download Diff File Expand all files Collapse all files

23
pyste/NEWS
View File

@@ -1,3 +1,26 @@
6 October 2003
Fixed bug reported by Niall Douglas (using his patch) about UniqueInt not
appearing correctly with --multiple.
Added precompiled header support on windows systems (using #pragma hdrstop).
Suggested by Niall Douglas.
Fixed a bug with -I directive and AllFromHeader. Reported by Scott Snyder.
4 October 2003
Added return_self, thanks for Niall Douglas for pointing out that it was
missing.
Added --file-list, where you can pass a file where the pyste files are listed
one per line. Also suggested by Niall Douglas.
Documentation has been finally updated, after a long wait. Please let me know
if you spot any mistake!
2 October 2003
Scott Snyder found a typo in ClassExporter that prevented -= and *= operators
from being exported. Thanks Scott!
20 September 2003
Added return_by_value in the list of policies supported. Thanks to Niall
Douglas for the remainder.

3
pyste/TODO
View File

@@ -10,3 +10,6 @@
- Virtual operators
- args() support
- --file-list, allowing the user to pass the filename of a file with the pyste
files

5
pyste/doc/adding_new_methods.html
View File

@@ -4,6 +4,7 @@
<title>Adding New Methods</title>
<link rel="stylesheet" href="theme/style.css" type="text/css">
<link rel="prev" href="global_variables.html">
<link rel="next" href="inserting_code.html">
</head>
<body>
<table width="100%" height="48" border="0" cellspacing="2">
@@ -20,7 +21,7 @@
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="global_variables.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><img src="theme/r_arr_disabled.gif" border="0"></td>
<td width="20"><a href="inserting_code.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<p>
@@ -66,7 +67,7 @@ Now from Python:</p>
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="global_variables.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><img src="theme/r_arr_disabled.gif" border="0"></td>
<td width="20"><a href="inserting_code.html"><img src="theme/r_arr.gif" border="0"></a></td>
</tr>
</table>
<br>

9
pyste/doc/exporting_an_entire_header.html
View File

@@ -60,6 +60,15 @@ the members of the header object like this:</p>
<span class=identifier>rename</span><span class=special>(</span><span class=identifier>hello</span><span class=special>.</span><span class=identifier>World</span><span class=special>.</span><span class=identifier>greet</span><span class=special>, </span><span class=string>&quot;Greet&quot;</span><span class=special>)
</span><span class=identifier>exclude</span><span class=special>(</span><span class=identifier>hello</span><span class=special>.</span><span class=identifier>World</span><span class=special>.</span><span class=identifier>set</span><span class=special>, </span><span class=string>&quot;Set&quot;</span><span class=special>)
</span></pre></code>
<table width="80%" border="0" align="center">
<tr>
<td class="note_box">
<img src="theme/note.gif"></img> <b>AllFromHeader is broken</b> in some cases. Until it is fixed,
use at you own risk.
</td>
</tr>
</table>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>

73
pyste/doc/inserting_code.html Normal file
View File

@@ -0,0 +1,73 @@
<html>
<head>
<!-- Generated by the Spirit (http://spirit.sf.net) QuickDoc -->
<title>Inserting Code</title>
<link rel="stylesheet" href="theme/style.css" type="text/css">
<link rel="prev" href="adding_new_methods.html">
</head>
<body>
<table width="100%" height="48" border="0" cellspacing="2">
<tr>
<td><img src="theme/c%2B%2Bboost.gif">
</td>
<td width="85%">
<font size="6" face="Verdana, Arial, Helvetica, sans-serif"><b>Inserting Code</b></font>
</td>
</tr>
</table>
<br>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="adding_new_methods.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><img src="theme/r_arr_disabled.gif" border="0"></td>
</tr>
</table>
<p>
You can insert arbitrary code in the generated cpps, just use the functions
<tt>declaration_code</tt> and <tt>module_code</tt>. This will insert the given string in the
respective sections. Example:</p>
<code><pre>
##<span class=identifier>file </span><span class=identifier>A</span><span class=special>.</span><span class=identifier>pyste
</span><span class=identifier>Class</span><span class=special>(</span><span class=string>&quot;A&quot;</span><span class=special>, </span><span class=string>&quot;A.h&quot;</span><span class=special>)
</span><span class=identifier>declaration_code</span><span class=special>(</span><span class=string>&quot;/* declaration_code() comes here */\n&quot;</span><span class=special>)
</span><span class=identifier>module_code</span><span class=special>(</span><span class=string>&quot;/* module_code() comes here */\n&quot;</span><span class=special>)
</span></pre></code>
<p>
Will generate:</p>
<code><pre>
<span class=comment>// Includes ====================================================================
</span><span class=preprocessor>#include </span><span class=special>&lt;</span><span class=identifier>boost</span><span class=special>/</span><span class=identifier>python</span><span class=special>.</span><span class=identifier>hpp</span><span class=special>&gt;
// </span><span class=identifier>Using </span><span class=special>=======================================================================
</span><span class=keyword>using </span><span class=keyword>namespace </span><span class=identifier>boost</span><span class=special>::</span><span class=identifier>python</span><span class=special>;
// </span><span class=identifier>Declarations </span><span class=special>================================================================
/* </span><span class=identifier>declaration_code</span><span class=special>() </span><span class=identifier>comes </span><span class=identifier>here </span><span class=special>*/
// </span><span class=identifier>Module </span><span class=special>======================================================================
</span><span class=identifier>BOOST_PYTHON_MODULE</span><span class=special>(</span><span class=identifier>A</span><span class=special>)
{
</span><span class=identifier>class_</span><span class=special>&lt; </span><span class=identifier>A </span><span class=special>&gt;(</span><span class=string>&quot;A&quot;</span><span class=special>, </span><span class=identifier>init</span><span class=special>&lt; &gt;())
.</span><span class=identifier>def</span><span class=special>(</span><span class=identifier>init</span><span class=special>&lt; </span><span class=keyword>const </span><span class=identifier>A</span><span class=special>&amp; &gt;())
;
/* </span><span class=identifier>module_code</span><span class=special>() </span><span class=identifier>comes </span><span class=identifier>here </span><span class=special>*/
}
</span></pre></code>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>
<td width="30"><a href="adding_new_methods.html"><img src="theme/l_arr.gif" border="0"></a></td>
<td width="20"><img src="theme/r_arr_disabled.gif" border="0"></td>
</tr>
</table>
<br>
<hr size="1"><p class="copyright">Copyright &copy; 2003 Bruno da Silva de Oliveira<br>Copyright &copy; 2002-2003 Joel de Guzman<br><br>
<font size="2">Permission to copy, use, modify, sell and distribute this document
is granted provided this copyright notice appears in all copies. This document
is provided &quot;as is&quot; without express or implied warranty, and with
no claim as to its suitability for any purpose. </font> </p>
</body>
</html>

2
pyste/doc/policies.html
View File

@@ -67,7 +67,7 @@ compile.
<td class="note_box">
<img src="theme/note.gif"></img>
Note that, for functions that return <tt>const T&amp;</tt>, the policy
Note that for functions that return <tt>const T&amp;</tt>, the policy
<tt>return_value_policy&lt;copy_const_reference&gt;()</tt> wil be used by default, because
that's normally what you want. You can change it to something else if you need
to, though.

194
pyste/doc/pyste.txt
View File

@@ -73,26 +73,36 @@ Well, now let's fire it up:
'''
>python pyste.py
Pyste version 0.6.5
Pyste version 0.9.26
Usage:
pyste [options] --module=<name> interface-files
pyste [options] interface-files
where options are:
-I <path> add an include path
-D <symbol> define symbol
--multiple create various cpps (one for each pyste file), instead
of only one (useful during development)
--out specify output filename (default: <module>.cpp)
in --multiple mode, this will be a directory
--no-using do not declare "using namespace boost";
use explicit declarations instead
--pyste-ns=<name> set the namespace where new types will be declared;
default is the empty namespace
--debug writes the xml for each file parsed in the current
directory
-h, --help print this help and exit
-v, --version print version information
--module=<name> The name of the module that will be generated;
defaults to the first interface filename, without
the extension.
-I <path> Add an include path
-D <symbol> Define symbol
--multiple Create various cpps, instead of only one
(useful during development)
--out=<name> Specify output filename (default: <module>.cpp)
in --multiple mode, this will be a directory
--no-using Do not declare "using namespace boost";
use explicit declarations instead
--pyste-ns=<name> Set the namespace where new types will be declared;
default is the empty namespace
--debug Writes the xml for each file parsed in the current
directory
--cache-dir=<dir> Directory for cache files (speeds up future runs)
--only-create-cache Recreates all caches (doesn't generate code).
--generate-main Generates the _main.cpp file (in multiple mode)
--file-list A file with one pyste file per line. Use as a
substitute for passing the files in the command
line.
-h, --help Print this help and exit
-v, --version Print version information
'''
]
@@ -102,12 +112,6 @@ The [^-I] and [^-D] are preprocessor flags, which are needed by GCCXML to parse
the header files correctly and by Pyste to find the header files declared in the
interface files.
[^--multiple] tells Pyste to generate multiple cpps for this module (one for
each header parsed) in the directory named by [^--out], instead of the usual
single cpp file. This mode is useful during development of a binding, because
you are constantly changing source files, re-generating the bindings and
recompiling. This saves a lot of time in compiling.
[^--out] names the output file (default: [^<module>.cpp]), or in multiple mode,
names a output directory for the files (default: [^<module>]).
@@ -122,6 +126,13 @@ default, Pyste uses the empty namespace.
[^--debug] will write in the current directory a xml file as outputted by GCCXML
for each header parsed. Useful for bug reports.
[^--file-list] names a file where each line points to a Pyste file. Use this instead
to pass the pyste files if you have a lot of them and your shell has some command line
size limit.
The other options are explained below, in [@#multiple_mode [*Multiple Mode]] and
[@#cache [*Cache]].
[^-h, --help, -v, --version] are self-explaining, I believe. ;)
So, the usage is simple enough:
@@ -130,13 +141,7 @@ So, the usage is simple enough:
will generate a file [^mymodule.cpp] in the same dir where the command was
executed. Now you can compile the file using the same instructions of the
[@../../doc/tutorial/doc/building_hello_world.html tutorial]. Or, if you prefer:
[pre >python pyste.py --module=mymodule --multiple file.pyste file2.pyste ...]
will create a directory named "mymodule" in the current directory, and will
generate a bunch of cpp files, one for each header exported. You can then
compile them all into a single shared library (or dll).
[@../../doc/tutorial/doc/building_hello_world.html tutorial].
[h2 Wait... how do I set those I and D flags?]
@@ -154,9 +159,62 @@ which for Visual C++ 6 is normally located at:
with that, you should have little trouble setting up the flags.
[blurb [$theme/note.gif][*A note about Psyco][br][br]
Although you don't have to install [@http://psyco.sourceforge.net/ Psyco] to use Pyste, if you do, Pyste will make use of it to speed up the wrapper generation. Speed ups of 30% can be achieved, so it's highly recommended.
Although you don't have to install [@http://psyco.sourceforge.net/ Psyco] to
use Pyste, if you do, Pyste will make use of it to speed up the wrapper
generation. Speed ups of 30% can be achieved, so it's highly recommended.
]
[h2 Multiple Mode]
The multiple mode is useful in large projects, where the presence of multiple
classes in a single file makes the compilation unpractical (excessive memory
usage, mostly).
The solution is make Pyste generate multiple files, more specifically one cpp
file for each Pyste file. This files will contain a function named after the
file, for instance Export_MyPysteFile, which will contain all the code to export
the classes, enums, etc. You can pass as much files as you want this way:
[pre >python pyste.py --module=mymodule file1.pyste file2.pyste]
This will create the files [^mymodule/file1.cpp] and [^mymodule/file2.cpp]. You
can then later do:
[pre >python pyste.py --module=mymodule file3.pyste]
and [^mymodule/file3.cpp] will be generated.
But compiling and linking this files won't be sufficient to generate your
extension. You have to also generate a file named [^main.cpp]; call pyste with
[*all] the Pyste files of your extension, and use the [^--generate-main] option:
[pre >python pyste.py --module=mymodule --generate-main file1.pyste file2.pyste file3.pyste]
Now compile and link all this files together and your extension is ready for
use.
[h2 Cache]
Pyste now supports a form of cache, which is a way to speed up the code
generation. Most of the time that Pyste takes to generate the code comes from
having to execute GCCXML (since being a front-end to GCC, it has to compile the
header files) and reading back the XML generated.
When you use the [^--cache-dir=<dir>] option, Pyste will dump in the specified
directory the generated XMLs to a file named after the Pyste file, with the
extension [^.pystec]. The next time you run with this option, Pyste will use
the cache, instead of calling GCCXML again:
[pre >python pyste.py --module=mymodule --cache-dir=cache file1.pyste]
Will generate [^file1.cpp] and [^cache/file1.pystec]. Next time you execute
this command, the cache file will be used. Note that Pyste doesn't do any check
to ensure that the cache is up to date, but you can configure your build system to do that for you.
When you run Pyste with [^--only-create-cache], all the cache files will be
created again, but no code will be generated.
[page The Interface Files]
The interface files are the heart of Pyste. The user creates one or more
@@ -198,6 +256,28 @@ We create a file named [^hello.pyste] and create instances of the classes
That will expose the class, the free function and the enum found in [^hello.h].
[h2 Inheritance]
Pyste automatically generates the correct code (specifying [^bases<>] in the
[^class_] declaration) [*if] the Class() function that exports the base classes
and their children are in the same Pyste file. If that's not the case, you have
to indicate that there's a relationship between the Pyste files using the
[^Import] function specifying the other Pyste file.
Suppose we have two classes, [^A] and [^B], and A is a base class for B. We
create two Pyste files:
[^A.pyste]:
Class("A", "A.h")
[^B.pyste]:
Import("A.pyste")
Class("B", "B.h")
Note that we specify that [^B] needs to know about [^A] to be properly exported.
[page:1 Renaming and Excluding]
You can easily rename functions, classes, member functions, attributes, etc. Just use the
@@ -233,10 +313,10 @@ The string inside the brackets is the same as the name of the operator in C++.[b
[h2 Virtual Member Functions]
Pyste automatically generates wrappers for virtual member functions, but you
may want to disable this behaviour (for performance reasons, or to let the
code more clean) if you do not plan to override the functions in Python. To do
this, use the function [^final]:
Pyste automatically generates wrappers for virtual member functions, but you may
want to disable this behaviour (for performance reasons, for instance) if you do
not plan to override the functions in Python. To do this, use the function
[^final]:
C = Class('C', 'C.h')
final(C.foo) # C::foo is a virtual member function
@@ -277,7 +357,7 @@ compile.
[blurb
[$theme/note.gif]
Note that, for functions that return [^const T&], the policy
Note that for functions that return [^const T&], the policy
[^return_value_policy<copy_const_reference>()] wil be used by default, because
that's normally what you want. You can change it to something else if you need
to, though.
@@ -344,9 +424,9 @@ Suppose you have this function:
std::vector<std::string> names();
But you don't want to export [^std::vector<std::string>], you want this function
to return a python list of strings. Boost.Python has excellent support for
that:
But you don't want to [@../../doc/v2/faq.html#question2 to export std::vector<std::string>],
you want this function to return a python list of strings. Boost.Python has
excellent support for things like that:
list names_wrapper()
{
@@ -445,6 +525,11 @@ the members of the header object like this:
rename(hello.World.greet, "Greet")
exclude(hello.World.set, "Set")
[blurb
[$theme/note.gif] [*AllFromHeader is broken] in some cases. Until it is fixed,
use at you own risk.
]
[page:1 Smart Pointers]
@@ -501,6 +586,7 @@ Beware of non-const global variables: changes in Python won't reflect in C++!
If you really must change them in Python, you will have to write some accessor
functions, and export those.
[page:1 Adding New Methods]
Suppose that you want to add a function to a class, turning it into a member
@@ -539,3 +625,35 @@ Now from Python:
Oh no! The knights who say Ni!
[page:1 Inserting Code]
You can insert arbitrary code in the generated cpps, just use the functions
[^declaration_code] and [^module_code]. This will insert the given string in the
respective sections. Example:
# file A.pyste
Class("A", "A.h")
declaration_code("/* declaration_code() comes here */\n")
module_code("/* module_code() comes here */\n")
Will generate:
// Includes ====================================================================
#include <boost/python.hpp>
// Using =======================================================================
using namespace boost::python;
// Declarations ================================================================
/* declaration_code() comes here */
// Module ======================================================================
BOOST_PYTHON_MODULE(A)
{
class_< A >("A", init< >())
.def(init< const A& >())
;
/* module_code() comes here */
}

8
pyste/doc/renaming_and_excluding.html
View File

@@ -60,10 +60,10 @@ To access the operators of a class, access the member <tt>operator</tt> like thi
<p>
The string inside the brackets is the same as the name of the operator in C++.<br></p>
<a name="virtual_member_functions"></a><h2>Virtual Member Functions</h2><p>
Pyste automatically generates wrappers for virtual member functions, but you
may want to disable this behaviour (for performance reasons, or to let the
code more clean) if you do not plan to override the functions in Python. To do
this, use the function <tt>final</tt>:</p>
Pyste automatically generates wrappers for virtual member functions, but you may
want to disable this behaviour (for performance reasons, for instance) if you do
not plan to override the functions in Python. To do this, use the function
<tt>final</tt>:</p>
<code><pre>
<span class=identifier>C </span><span class=special>= </span><span class=identifier>Class</span><span class=special>(</span><span class=literal>'C'</span><span class=special>, </span><span class=literal>'C.h'</span><span class=special>)
</span><span class=identifier>final</span><span class=special>(</span><span class=identifier>C</span><span class=special>.</span><span class=identifier>foo</span><span class=special>) </span>##<span class=identifier>C</span><span class=special>::</span><span class=identifier>foo </span><span class=identifier>is </span><span class=identifier>a </span><span class=keyword>virtual </span><span class=identifier>member </span><span class=identifier>function

107
pyste/doc/running_pyste.html
View File

@@ -47,26 +47,36 @@ Well, now let's fire it up:</p>
&gt;python pyste.py
Pyste version 0.6.5
Pyste version 0.9.26
Usage:
pyste [options] --module=&lt;name&gt; interface-files
pyste [options] interface-files
where options are:
-I &lt;path&gt; add an include path
-D &lt;symbol&gt; define symbol
--multiple create various cpps (one for each pyste file), instead
of only one (useful during development)
--out specify output filename (default: &lt;module&gt;.cpp)
in --multiple mode, this will be a directory
--no-using do not declare &quot;using namespace boost&quot;;
use explicit declarations instead
--pyste-ns=&lt;name&gt; set the namespace where new types will be declared;
default is the empty namespace
--debug writes the xml for each file parsed in the current
directory
-h, --help print this help and exit
-v, --version print version information
--module=&lt;name&gt; The name of the module that will be generated;
defaults to the first interface filename, without
the extension.
-I &lt;path&gt; Add an include path
-D &lt;symbol&gt; Define symbol
--multiple Create various cpps, instead of only one
(useful during development)
--out=&lt;name&gt; Specify output filename (default: &lt;module&gt;.cpp)
in --multiple mode, this will be a directory
--no-using Do not declare &quot;using namespace boost&quot;;
use explicit declarations instead
--pyste-ns=&lt;name&gt; Set the namespace where new types will be declared;
default is the empty namespace
--debug Writes the xml for each file parsed in the current
directory
--cache-dir=&lt;dir&gt; Directory for cache files (speeds up future runs)
--only-create-cache Recreates all caches (doesn't generate code).
--generate-main Generates the _main.cpp file (in multiple mode)
--file-list A file with one pyste file per line. Use as a
substitute for passing the files in the command
line.
-h, --help Print this help and exit
-v, --version Print version information
</pre></code><p>
Options explained:</p>
@@ -76,12 +86,6 @@ GCCXML</a> to parse
the header files correctly and by Pyste to find the header files declared in the
interface files.</p>
<p>
<tt>--multiple</tt> tells Pyste to generate multiple cpps for this module (one for
each header parsed) in the directory named by <tt>--out</tt>, instead of the usual
single cpp file. This mode is useful during development of a binding, because
you are constantly changing source files, re-generating the bindings and
recompiling. This saves a lot of time in compiling.</p>
<p>
<tt>--out</tt> names the output file (default: <tt>&lt;module&gt;.cpp</tt>), or in multiple mode,
names a output directory for the files (default: <tt>&lt;module&gt;</tt>).</p>
<p>
@@ -97,6 +101,15 @@ default, Pyste uses the empty namespace.</p>
GCCXML</a>
for each header parsed. Useful for bug reports.</p>
<p>
<tt>--file-list</tt> names a file where each line points to a Pyste file. Use this instead
to pass the pyste files if you have a lot of them and your shell has some command line
size limit.</p>
<p>
The other options are explained below, in <a href="#multiple_mode">
<b>Multiple Mode</b></a> and
<a href="#cache">
<b>Cache</b></a>.</p>
<p>
<tt>-h, --help, -v, --version</tt> are self-explaining, I believe. ;)</p>
<p>
So, the usage is simple enough:</p>
@@ -104,11 +117,7 @@ So, the usage is simple enough:</p>
will generate a file <tt>mymodule.cpp</tt> in the same dir where the command was
executed. Now you can compile the file using the same instructions of the
<a href="../../doc/tutorial/doc/building_hello_world.html">
tutorial</a>. Or, if you prefer:</p>
<code><pre>&gt;python pyste.py --module=mymodule --multiple file.pyste file2.pyste ...</pre></code><p>
will create a directory named &quot;mymodule&quot; in the current directory, and will
generate a bunch of cpp files, one for each header exported. You can then
compile them all into a single shared library (or dll).</p>
tutorial</a>. </p>
<a name="wait____how_do_i_set_those_i_and_d_flags_"></a><h2>Wait... how do I set those I and D flags?</h2><p>
Don't worry: normally <a href="http://www.gccxml.org">
GCCXML</a> is already configured correctly for your plataform,
@@ -129,10 +138,52 @@ with that, you should have little trouble setting up the flags.</p>
<td class="note_box">
<img src="theme/note.gif"></img><b>A note about Psyco</b><br><br>
Although you don't have to install <a href="http://psyco.sourceforge.net/">
Psyco</a> to use Pyste, if you do, Pyste will make use of it to speed up the wrapper generation. Speed ups of 30% can be achieved, so it's highly recommended.
Psyco</a> to
use Pyste, if you do, Pyste will make use of it to speed up the wrapper
generation. Speed ups of 30% can be achieved, so it's highly recommended.
</td>
</tr>
</table>
<a name="multiple_mode"></a><h2>Multiple Mode</h2><p>
The multiple mode is useful in large projects, where the presence of multiple
classes in a single file makes the compilation unpractical (excessive memory
usage, mostly). </p>
<p>
The solution is make Pyste generate multiple files, more specifically one cpp
file for each Pyste file. This files will contain a function named after the
file, for instance Export_MyPysteFile, which will contain all the code to export
the classes, enums, etc. You can pass as much files as you want this way:</p>
<code><pre>&gt;python pyste.py --module=mymodule file1.pyste file2.pyste</pre></code><p>
This will create the files <tt>mymodule/file1.cpp</tt> and <tt>mymodule/file2.cpp</tt>. You
can then later do:</p>
<code><pre>&gt;python pyste.py --module=mymodule file3.pyste</pre></code><p>
and <tt>mymodule/file3.cpp</tt> will be generated.</p>
<p>
But compiling and linking this files won't be sufficient to generate your
extension. You have to also generate a file named <tt>main.cpp</tt>; call pyste with
<b>all</b> the Pyste files of your extension, and use the <tt>--generate-main</tt> option:</p>
<code><pre>&gt;python pyste.py --module=mymodule --generate-main file1.pyste file2.pyste file3.pyste</pre></code><p>
Now compile and link all this files together and your extension is ready for
use.</p>
<a name="cache"></a><h2>Cache</h2><p>
Pyste now supports a form of cache, which is a way to speed up the code
generation. Most of the time that Pyste takes to generate the code comes from
having to execute <a href="http://www.gccxml.org">
GCCXML</a> (since being a front-end to GCC, it has to compile the
header files) and reading back the XML generated. </p>
<p>
When you use the <tt>--cache-dir=&lt;dir&gt;</tt> option, Pyste will dump in the specified
directory the generated XMLs to a file named after the Pyste file, with the
extension <tt>.pystec</tt>. The next time you run with this option, Pyste will use
the cache, instead of calling <a href="http://www.gccxml.org">
GCCXML</a> again:</p>
<code><pre>&gt;python pyste.py --module=mymodule --cache-dir=cache file1.pyste</pre></code><p>
Will generate <tt>file1.cpp</tt> and <tt>cache/file1.pystec</tt>. Next time you execute
this command, the cache file will be used. Note that Pyste doesn't do any check
to ensure that the cache is up to date, but you can configure your build system to do that for you.</p>
<p>
When you run Pyste with <tt>--only-create-cache</tt>, all the cache files will be
created again, but no code will be generated.</p>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>

22
pyste/doc/the_interface_files.html
View File

@@ -64,6 +64,28 @@ We create a file named <tt>hello.pyste</tt> and create instances of the classes
</span></pre></code>
<p>
That will expose the class, the free function and the enum found in <tt>hello.h</tt>. </p>
<a name="inheritance"></a><h2>Inheritance</h2><p>
Pyste automatically generates the correct code (specifying <tt>bases&lt;&gt;</tt> in the
<tt>class_</tt> declaration) <b>if</b> the Class() function that exports the base classes
and their children are in the same Pyste file. If that's not the case, you have
to indicate that there's a relationship between the Pyste files using the
<tt>Import</tt> function specifying the other Pyste file.</p>
<p>
Suppose we have two classes, <tt>A</tt> and <tt>B</tt>, and A is a base class for B. We
create two Pyste files:</p>
<p>
<tt>A.pyste</tt>:</p>
<code><pre>
<span class=identifier>Class</span><span class=special>(</span><span class=string>&quot;A&quot;</span><span class=special>, </span><span class=string>&quot;A.h&quot;</span><span class=special>)
</span></pre></code>
<p>
<tt>B.pyste</tt>:</p>
<code><pre>
<span class=identifier>Import</span><span class=special>(</span><span class=string>&quot;A.pyste&quot;</span><span class=special>)
</span><span class=identifier>Class</span><span class=special>(</span><span class=string>&quot;B&quot;</span><span class=special>, </span><span class=string>&quot;B.h&quot;</span><span class=special>)
</span></pre></code>
<p>
Note that we specify that <tt>B</tt> needs to know about <tt>A</tt> to be properly exported.</p>
<table border="0">
<tr>
<td width="30"><a href="../index.html"><img src="theme/u_arr.gif" border="0"></a></td>

9
pyste/doc/wrappers.html
View File

@@ -30,10 +30,11 @@ Suppose you have this function:</p>
<span class=identifier>std</span><span class=special>::</span><span class=identifier>vector</span><span class=special>&lt;</span><span class=identifier>std</span><span class=special>::</span><span class=identifier>string</span><span class=special>&gt; </span><span class=identifier>names</span><span class=special>();
</span></pre></code>
<p>
But you don't want to export <tt>std::vector&lt;std::string&gt;</tt>, you want this function
to return a python list of strings. <a href="../../index.html">
Boost.Python</a> has excellent support for
that:</p>
But you don't want to <a href="../../doc/v2/faq.html#question2">
to export std::vector&lt;std::string&gt;</a>,
you want this function to return a python list of strings. <a href="../../index.html">
Boost.Python</a> has
excellent support for things like that:</p>
<code><pre>
<span class=identifier>list </span><span class=identifier>names_wrapper</span><span class=special>()
{

5
pyste/index.html
View File

@@ -75,6 +75,11 @@
<a href="doc/adding_new_methods.html">Adding New Methods</a>
</td>
</tr>
<tr>
<td class="toc_cells_L1">
<a href="doc/inserting_code.html">Inserting Code</a>
</td>
</tr>
</table>
<br>
<hr size="1"><p class="copyright">Copyright &copy; 2003 Bruno da Silva de Oliveira<br>Copyright &copy; 2002-2003 Joel de Guzman<br><br>

7
pyste/src/Pyste/ClassExporter.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
import exporters
from Exporter import Exporter
from declarations import *
@@ -425,7 +430,7 @@ class ClassExporter(Exporter):
self.Add('template', holder(self.class_.FullName()))
# operators natively supported by boost
BOOST_SUPPORTED_OPERATORS = '+ - * / % ^ & ! ~ | < > == != <= >= << >> && || += -='\
BOOST_SUPPORTED_OPERATORS = '+ - * / % ^ & ! ~ | < > == != <= >= << >> && || += -= '\
'*= /= %= ^= &= |= <<= >>='.split()
# create a map for faster lookup
BOOST_SUPPORTED_OPERATORS = dict(zip(BOOST_SUPPORTED_OPERATORS, range(len(BOOST_SUPPORTED_OPERATORS))))

5
pyste/src/Pyste/CodeExporter.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from Exporter import Exporter
#==============================================================================

8
pyste/src/Pyste/CppParser.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from GCCXMLParser import ParseDeclarations
import tempfile
import shutil
@@ -151,7 +156,8 @@ class CppParser:
if declarations is None:
declarations = self.ParseWithGCCXML(header, tail)
self.CreateCache(header, interface, tail, declarations)
return declarations, header
header_fullpath = os.path.abspath(self.FindHeader(header))
return declarations, header_fullpath
def CacheFileName(self, interface):

56
pyste/src/Pyste/EnumExporter.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from Exporter import Exporter
from settings import *
import utils
@@ -47,44 +52,23 @@ class EnumExporter(Exporter):
exported_names[self.enum.FullName()] = 1
UNIQUE_INT_EXPORTED = False
def ExportUniqueInt(self, codeunit):
if not EnumExporter.UNIQUE_INT_EXPORTED:
write = lambda s: codeunit.Write('declaration', s)
write('// Unique type for unnamed enums\n')
write('template<int num>\n')
write('struct UniqueInt {\n')
write(' int v;\n')
write(' enum { value=num };\n')
write(' UniqueInt(int v_):\n')
write(' v(v_)\n')
write(' {}\n')
write(' operator int() const\n')
write(' { return v; }\n')
write('};\n')
EnumExporter.UNIQUE_INT_EXPORTED = True
write = lambda s: codeunit.Write('declaration', s)
write('// Unique type for unnamed enums\n')
write('#ifndef PYSTE_UNIQUE_INT_DEFINED\n')
write('#define PYSTE_UNIQUE_INT_DEFINED\n')
write('template<int num>\n')
write('struct UniqueInt {\n')
write(' int v;\n')
write(' enum { value=num };\n')
write(' UniqueInt(int v_):\n')
write(' v(v_)\n')
write(' {}\n')
write(' operator int() const\n')
write(' { return v; }\n')
write('};\n')
write('#endif // PYSTE_UNIQUE_INT_DEFINED \n')
#def Export(self, codeunit, exported_names):
# if not self.info.exclude:
# indent = self.INDENT
# in_indent = self.INDENT*2
# rename = self.info.rename or self.enum.name
# full_name = self.enum.FullName()
# if rename == "$_0" or rename == '._0':
# full_name = "int"
# rename = "unnamed"
# code = indent + namespaces.python
# code += 'enum_< %s >("%s")\n' % (full_name, rename)
# for name in self.enum.values:
# rename = self.info[name].rename or name
# value_fullname = self.enum.ValueFullName(name)
# code += in_indent + '.value("%s", %s)\n' % (rename, value_fullname)
# code += indent + ';\n\n'
# codeunit.Write('module', code)
# exported_names[self.Name()] = 1
def Name(self):
return self.info.name

5
pyste/src/Pyste/Exporter.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
import os.path
#==============================================================================

5
pyste/src/Pyste/FunctionExporter.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from Exporter import Exporter
from policies import *
from declarations import *

11
pyste/src/Pyste/GCCXMLParser.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from declarations import *
from elementtree.ElementTree import ElementTree
from xml.parsers.expat import ExpatError
@@ -313,8 +318,14 @@ class GCCXMLParser(object):
self.ParseClass(id, element)
FUNDAMENTAL_RENAME = {
'long long int' : 'boost::int64_t',
'long long unsigned int' : 'boost::uint64_t',
}
def ParseFundamentalType(self, id, element):
name = element.get('name')
name = self.FUNDAMENTAL_RENAME.get(name, name)
type_ = FundamentalType(name)
self.Update(id, type_)

7
pyste/src/Pyste/HeaderExporter.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from Exporter import Exporter
from ClassExporter import ClassExporter
from FunctionExporter import FunctionExporter
@@ -33,7 +38,7 @@ class HeaderExporter(Exporter):
header = os.path.normpath(self.parser_header)
for decl in self.declarations:
# check if this declaration is in the header
location = os.path.normpath(decl.location[0])
location = os.path.abspath(decl.location[0])
if location == header and not self.IsInternalName(decl.name):
# ok, check the type of the declaration and export it accordingly
self.HandleDeclaration(decl, codeunit, exported_names)

5
pyste/src/Pyste/MultipleCodeUnit.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from SingleCodeUnit import SingleCodeUnit
import os
import utils

22
pyste/src/Pyste/SingleCodeUnit.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from settings import namespaces
import settings
from utils import remove_duplicated_lines, left_equals
@@ -23,7 +28,7 @@ class SingleCodeUnit:
# define the avaiable sections
self.code = {}
# include section
self.code['include'] = '#include <boost/python.hpp>\n'
self.code['include'] = ''
# declaration section (inside namespace)
self.code['declaration'] = ''
# declaration (outside namespace)
@@ -66,10 +71,23 @@ class SingleCodeUnit:
else:
flag = 'a'
fout = SmartFile(self.filename, flag)
fout.write('\n')
# includes
# boost.python header
fout.write(left_equals('Boost Includes'))
fout.write('#include <boost/python.hpp>\n')
# include numerical boost for int64 definitions
fout.write('#include <boost/cstdint.hpp>\n')
if settings.msvc:
# include precompiled header directive
fout.write('#ifdef _MSC_VER\n')
fout.write('#pragma hdrstop\n')
fout.write('#endif\n')
fout.write('\n')
# other includes
if self.code['include']:
fout.write(left_equals('Includes'))
includes = remove_duplicated_lines(self.code['include'])
fout.write('\n' + left_equals('Includes'))
fout.write(includes)
fout.write(space)
# using

5
pyste/src/Pyste/SmartFile.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
import os
import md5

5
pyste/src/Pyste/VarExporter.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from Exporter import Exporter
from settings import *
import utils

6
pyste/src/Pyste/__init__.py
View File

@@ -0,0 +1,6 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)

5
pyste/src/Pyste/declarations.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
'''
Defines classes that represent declarations found in C++ header files.

5
pyste/src/Pyste/exporters.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
# a list of Exporter instances
exporters = []

5
pyste/src/Pyste/exporterutils.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
'''
Various helpers for interface files.
'''

5
pyste/src/Pyste/infos.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
import os.path
import copy
import exporters

15
pyste/src/Pyste/policies.py
View File

@@ -1,10 +1,16 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
class Policy:
class Policy(object):
'Represents one of the call policies of boost.python.'
def __init__(self):
raise RuntimeError, "Can't create an instance of the class Policy"
if type(self) is Policy:
raise RuntimeError, "Can't create an instance of the class Policy"
def Code(self):
@@ -74,6 +80,11 @@ class return_value_policy(Policy):
c += self._next()
return c
class return_self(Policy):
def Code(self):
return 'return_self<>'
# values for return_value_policy
reference_existing_object = 'reference_existing_object'

28
pyste/src/Pyste/pyste.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
"""
Pyste version %s
@@ -23,6 +28,9 @@ where options are:
--cache-dir=<dir> Directory for cache files (speeds up future runs)
--only-create-cache Recreates all caches (doesn't generate code).
--generate-main Generates the _main.cpp file (in multiple mode)
--file-list A file with one pyste file per line. Use as a
substitute for passing the files in the command
line.
-h, --help Print this help and exit
-v, --version Print version information
"""
@@ -43,7 +51,7 @@ from CppParser import CppParser, CppParserError
import time
import declarations
__version__ = '0.9.26'
__version__ = '0.9.27'
def RecursiveIncludes(include):
'Return a list containg the include dir and all its subdirectories'
@@ -72,6 +80,19 @@ def ProcessIncludes(includes):
index += 1
def ReadFileList(filename):
f = file(filename)
files = []
try:
for line in f:
line = line.strip()
if line:
files.append(line)
finally:
f.close()
return files
def ParseArguments():
def Usage():
@@ -83,7 +104,7 @@ def ParseArguments():
sys.argv[1:],
'R:I:D:vh',
['module=', 'multiple', 'out=', 'no-using', 'pyste-ns=', 'debug', 'cache-dir=',
'only-create-cache', 'version', 'generate-main', 'help'])
'only-create-cache', 'version', 'generate-main', 'file-list=', 'help'])
except getopt.GetoptError, e:
print
print 'ERROR:', e
@@ -122,6 +143,8 @@ def ParseArguments():
cache_dir = value
elif opt == '--only-create-cache':
create_cache = True
elif opt == '--file-list':
files += ReadFileList(value)
elif opt in ['-h', '--help']:
Usage()
elif opt in ['-v', '--version']:
@@ -193,6 +216,7 @@ def CreateContext():
context['return_opaque_pointer'] = return_opaque_pointer
context['manage_new_object'] = manage_new_object
context['return_by_value'] = return_by_value
context['return_self'] = return_self
# utils
context['Wrapper'] = exporterutils.FunctionWrapper
context['declaration_code'] = lambda code: infos.CodeInfo(code, 'declaration-outside')

8
pyste/src/Pyste/settings.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
#==============================================================================
# Global information
@@ -11,3 +16,6 @@ class namespaces:
pyste = ''
python = '' # default is to not use boost::python namespace explicitly, so
# use the "using namespace" statement instead
import sys
msvc = sys.platform == 'win32'

5
pyste/src/Pyste/utils.py
View File

@@ -1,3 +1,8 @@
# Copyright Bruno da Silva de Oliveira 2003. Use, modification and
# distribution is subject to the Boost Software License, Version 1.0.
# (See accompanying file LICENSE_1_0.txt or copy at
# http:#www.boost.org/LICENSE_1_0.txt)
from __future__ import generators
import string
import sys