diff --git a/build/Jamfile.v2 b/build/Jamfile.v2 index dbb16b09..e01a27b7 100644 --- a/build/Jamfile.v2 +++ b/build/Jamfile.v2 @@ -7,11 +7,28 @@ import modules ; import python ; +if ! [ python.configured ] && ! ( --without-python in [ modules.peek : ARGV ] ) +{ + # Attempt default configuration of python + import toolset : using ; + using python ; + + if ! [ python.configured ] + { + ECHO "WARNING: No python installation configured and autoconfiguration" ; + ECHO " failed. See http://www.boost.org/libs/python/doc/building.html" ; + ECHO " for configuration instructions or pass --without-python to" ; + ECHO " suppress this message and silently skip all Boost.Python targets" ; + } +} project boost/python : source-location ../src ; +rule cond ( test ? : yes * : no * ) { if $(test) { return $(yes) ; } else { return $(no) ; } } +rule unless ( test ? : yes * : no * ) { if ! $(test) { return $(yes) ; } else { return $(no) ; } } + lib boost_python : # sources numeric.cpp @@ -22,7 +39,6 @@ lib boost_python str.cpp slice.cpp - aix_init_module.cpp converter/from_python.cpp converter/registry.cpp converter/type_id.cpp @@ -60,11 +76,19 @@ lib boost_python # python_for_extensions is a target defined by Boost.Build to # provide the Python include paths, and on Windows, the Python # import library, as usage requirements. - /python//python_for_extensions - + [ cond [ python.configured ] : /python//python_for_extensions ] + + # we prevent building when there is no python available + # as it's not possible anyway, and to cause dependents to + # fail to build + [ unless [ python.configured ] : no ] + + on:BOOST_DEBUG_PYTHON : # default build shared : # usage requirements - static:BOOST_PYTHON_STATIC_LIB - shared:BOOST_PYTHON_DYNAMIC_LIB + static:BOOST_PYTHON_STATIC_LIB + on:BOOST_DEBUG_PYTHON ; + +boost-install boost_python ; diff --git a/doc/PyConDC_2003/bpl.html b/doc/PyConDC_2003/bpl.html old mode 100755 new mode 100644 diff --git a/doc/PyConDC_2003/bpl.pdf b/doc/PyConDC_2003/bpl.pdf old mode 100755 new mode 100644 diff --git a/doc/PyConDC_2003/python_cpp_mix.jpg b/doc/PyConDC_2003/python_cpp_mix.jpg old mode 100755 new mode 100644 diff --git a/doc/PyConDC_2003/python_cpp_mix.png b/doc/PyConDC_2003/python_cpp_mix.png old mode 100755 new mode 100644 diff --git a/doc/building.html b/doc/building.html index 94f39955..9e7e6711 100644 --- a/doc/building.html +++ b/doc/building.html @@ -9,60 +9,63 @@
-

Boost.Python Build and Test HOWTO

+

Boost.Python Build and Test HOWTO

-
-

Contents

+ -
-

1   Requirements

-

Boost.Python requires Python 2.21 or newer.

+
+

1   Requirements

+

Boost.Python requires Python 2.21 or newer.

-
-

2   Background

+
+

2   Background

There are two basic models for combining C++ and Python:

    -
  • extending, in which the end-user launches the Python interpreter +
  • extending, in which the end-user launches the Python interpreter executable and imports Python “extension modules” written in C++. Think of taking a library written in C++ and giving it a Python interface so Python programmers can use it. From Python, these modules look just like regular Python modules.
    • -
  • embedding, in which the end-user launches a program written +
  • embedding, in which the end-user launches a program written in C++ that in turn invokes the Python interpreter as a library subroutine. Think of adding scriptability to an existing application.

The key distinction between extending and embedding is the location -of C++' main() function: in the Python interpreter executable, +of the C++ main() function: in the Python interpreter executable, or in some other program, respectively. Note that even when -embedding Python in another program, extension modules are often +embedding Python in another program, extension modules are often the best way to make C/C++ functionality accessible to Python code, so the use of extension modules is really at the heart of both models.

@@ -71,127 +74,281 @@ dynamically-loaded libraries with a single entry point, which means you can change them without rebuilding either the other extension modules or the executable containing main().

-
-

3   Getting Boost.Python Binaries

-

Since Boost.Python is a separately-compiled (as opposed to -header-only) library, its user relies on the services of a -Boost.Python library binary.

-
-

3.1   No-Install Quickstart

-

If you just want to get started quickly building and testing -Boost.Python extension modules, or embedding Python in an -executable, you don't need to worry about installing Boost.Python -binaries explicitly. These instructions use Boost.Build projects, +

+

3   No-Install Quickstart

+

There is no need to “install Boost” in order to get started using +Boost.Python. These instructions use Boost.Build projects, which will build those binaries as soon as they're needed. Your first tests may take a little longer while you wait for Boost.Python to build, but doing things this way will save you from worrying about build intricacies like which library binaries to use -for a specific compiler configuration.

+for a specific compiler configuration and figuring out the right +compiler options to use yourself.

+

Note

Of course it's possible to use other build systems to build Boost.Python and its extensions, but they are not -officially supported by Boost and 99% of all “I can't build -Boost.Python” problems come from trying to use another build -system.

-

If you want to use another system anyway, we suggest that you -follow these instructions, and then invoke bjam with the --a -ofilename option to dump the build commands it executes -to a file, so you can see what your build system needs to do.

+officially supported by Boost. Moreover 99% of all “I can't +build Boost.Python” problems come from trying to use another +build system without first following these instructions.

+

If you want to use another system anyway, we suggest that you +follow these instructions, and then invoke bjam with the

+
+-a -ofilename
+
+

options to dump the build commands it executes to a file, so +you can see what your alternate build system needs to do.

+
+ +
+

3.1   Basic Procedure

+
    +

  1. Get Boost; see sections 1 and 2 [Unix/Linux, Windows] of the +Boost Getting Started Guide.

    +
    2. +

  2. Get the bjam build driver. See section 5 [Unix/Linux, +Windows] of the Boost Getting Started Guide.

    +
    3. +

  3. cd into the libs/python/example/quickstart/ directory of your +Boost installation, which contains a small example project.

    +
    4. +

  4. Invoke bjam. Replace the “stage“ argument from the +example invocation from section 5 of the Getting Started +Guide with “test,“ to build all the test targets. Also add +the argument “--verbose-test” to see the output generated by +the tests when they are run.

    +

    On Windows, your bjam invocation might look something like:

    +
    +C:\boost_1_34_0\…\quickstart> bjam toolset=msvc --verbose-test test
+
    +

    and on Unix variants, perhaps,

    +
    +~/boost_1_34_0/…/quickstart$ bjam toolset=gcc --verbose-test test
+
    +
    5. +
+
+

Note to Windows Users

+

For the sake of concision, the rest of this guide will use +unix-style forward slashes in pathnames instead of the +backslashes with which you may be more familiar. The forward +slashes should work everywhere except in Command Prompt +windows, where you should use backslashes.

+
+

If you followed this procedure successfully, you will have built an +extension module called extending and tested it by running a +Python script called test_extending.py. You will also have +built and run a simple application called embedding that embeds +python.

+
+
+

3.2   In Case of Trouble

+

If you're seeing lots of compiler and/or linker error messages, +it's probably because Boost.Build is having trouble finding your +Python installation. You might want to pass the +--debug-configuration option to bjam the first few times +you invoke it, to make sure that Boost.Build is correctly locating +all the parts of your Python installation. If it isn't, consider +Configuring Boost.Build as detailed below.

+

If you're still having trouble, Someone on one of the following +mailing lists may be able to help:

+ +
+
+

3.3   In Case Everything Seemed to Work

+

Rejoice! If you're new to Boost.Python, at this point it might be +a good idea to ignore build issues for a while and concentrate on +learning the library by going through the tutorial and perhaps +some of the reference documentation, trying out what you've +learned about the API by modifying the quickstart project.

+
+
+

3.4   Modifying the Example Project

+

If you're content to keep your extension module forever in one +source file called extending.cpp, inside your Boost +distribution, and import it forever as extending, then you can +stop here. However, it's likely that you will want to make a few +changes. There are a few things you can do without having to learn +Boost.Build in depth.

+

The project you just built is specified in two files in the current +directory: boost-build.jam, which tells bjam where it can +find the interpreted code of the Boost build system, and +Jamroot, which describes the targets you just built. These +files are heavily commented, so they should be easy to modify. +Take care, however, to preserve whitespace. Punctuation such as +; will not be recognized as intended by bjam if it is not +surrounded by whitespace.

+
+

Relocate the Project

+

You'll probably want to copy this project elsewhere so you can +change it without modifying your Boost distribution. To do that, +simply

+
    +
  1. copy the entire libs/python/example/quickstart/ directory +into a new directory.
    2. +
  2. In the new copies of boost-build.jam and Jamroot, locate +the relative path near the top of the file that is clearly +marked by a comment, and edit that path so that it refers to the +same directory your Boost distribution as it referred to when +the file was in its original location in the +libs/python/example/quickstart/ directory.
    3. +
+

For example, if you moved the project from +/home/dave/boost_1_34_0/libs/python/example/quickstart to +/home/dave/my-project, you could change the first path in +boost-build.jam from

+
+../../../../tools/build/v2
+
+

to

+
+/home/dave/boost_1_34_0/tools/build/v2
+
+

and change the first path in Jamroot from

+
+../../../..
+
+

to

+
+/home/dave/boost_1_34_0
+
+
+
+

Add New or Change Names of Existing Source Files

+

The names of additional source files involved in building your +extension module or embedding application can be listed in +Jamroot right alongside extending.cpp or embedding.cpp +respectively. Just be sure to leave whitespace around each +filename:

+
+… file1.cpp file2.cpp file3.cpp …
+
+

Naturally, if you want to change the name of a source file you can +tell Boost.Build about it by editing the name in Jamroot.

+
+
+

Change the Name of your Extension Module

+

The name of the extension module is determined by two things:

+
    +
  1. the name in Jamroot immediately following python-extension, and
    2. +
  2. the name passed to BOOST_PYTHON_MODULE in extending.cpp.
    3. +
+

To change the name of the extension module from extending to +hello, you'd edit Jamroot, changing

+
+python-extension extending : extending.cpp ;
+
+

to

+
+python-extension hello : extending.cpp ;
+
+

and you'd edit extending.cpp, changing

+
+BOOST_PYTHON_MODULE(extending)
+
+

to

+
+BOOST_PYTHON_MODULE(hello)
+
-
-

3.2   Installing Boost.Python on your System

-

If you need a regular, installation of the Boost.Python library -binaries on your system, the Boost Getting Started Guide will -walk you through the steps of installing one. If building binaries +

+
+

4   Installing Boost.Python on your System

+

Since Boost.Python is a separately-compiled (as opposed to +header-only) library, its user relies on the services of a +Boost.Python library binary.

+

If you need a regular installation of the Boost.Python library +binaries on your system, the Boost Getting Started Guide will +walk you through the steps of creating one. If building binaries from source, you might want to supply the --with-python argument to bjam (or the --with-libraries=python argument to configure), so only the Boost.Python binary will be built, rather than all the Boost binaries.

-
-
-

4   Configuring Boost.Build

-

As described in the Boost.Build reference manual, a file called -user-config.jam in your home -directory7 is used to -describe the build resources available to the build system. You'll -need to tell it about your Python installation.

+
+

5   Configuring Boost.Build

+

As described in the Boost.Build reference manual, a file called +user-config.jam in your home directory6 is used to +specify the tools and libraries available to the build system. You +may need to create or edit user-config.jam to tell Boost.Build +how to invoke Python, #include its headers, and link with its +libraries.

Users of Unix-Variant OSes

If you are using a unix-variant OS and you ran Boost's configure script, it may have generated a -user-config.jam for you.4 If your configure/make sequence was successful and Boost.Python binaries +user-config.jam for you.4 If your configure/make sequence was successful and Boost.Python binaries were built, your user-config.jam file is probably already correct.

-

If you have a fairly “standard” python installation for your -platform, there's very little you need to do to describe it. -Simply having

+

If you have one fairly “standard” python installation for your +platform, you might not need to do anything special to describe it. If +you haven't configured python in user-config.jam (and you don't +specify --without-python on the Boost.Build command line), +Boost.Build will automatically execute the equivalent of

 import toolset : using ;
 using python ;
-

in a user-config.jam file in your home directory7 -should be enough.6 For more complicated setups, -see Advanced Configuration.

-
-

Note

-

You might want to pass the --debug-configuration -option to bjam the first few times you invoke it, to make -sure that Boost.Build is correctly locating all the parts of -your Python installation. If it isn't, consider passing some of -the optional Python configuration parameters detailed below.

-
-
-
-

5   Building an Extension Module

-
-
-

6   Testing

-
-
-

7   Advanced Configuration

+

which automatically looks for Python in the most likely places. +However, that only happens when using the Boost.Python project file +(e.g. when referred to by another project as in the quickstart +method). If instead you are linking against separately-compiled +Boost.Python binaries, you should set up a user-config.jam file +with at least the minimal incantation above.

+
+

5.1   Python Configuration Parameters

If you have several versions of Python installed, or Python is installed in an unusual way, you may want to supply any or all of the following optional parameters to using python.

-
-

7.1   Python Configuration Parameters

version
the version of Python to use. Should be in Major.Minor format, for example, 2.3. Do not include the subminor version (i.e. not 2.5.1). If you have multiple Python versions installed, the version will usually be the only -additional argument required.
+configuration argument required.
cmd-or-prefix
-
preferably, a command that invokes a Python -interpreter. Alternatively, the installation prefix for Python -libraries and header files. Use the alternative formulation if -there is no appropriate Python executable available.
+
preferably, a command that invokes a Python interpreter. +Alternatively, the installation prefix for Python libraries and +header files. Only use the alternative formulation if there is +no appropriate Python executable available.
includes
-
the #include path for Python headers.
+
the #include paths for Python headers. Normally the correct +path(s) will be automatically deduced from version and/or +cmd-or-prefix.
libraries
the path to Python library binaries. On MacOS/Darwin, -you can also pass the path of the Python framework.
+you can also pass the path of the Python framework. Normally the +correct path(s) will be automatically deduced from version +and/or cmd-or-prefix.
condition
if specified, should be a set of Boost.Build properties that are matched against the build configuration when -Boost.Build selects a Python configuration to use.
+Boost.Build selects a Python configuration to use. See examples +below for details.
extension-suffix
A string to append to the name of extension modules before the true filename extension. You almost certainly don't need to use this. Usually this suffix is only used when targeting a Windows debug build of Python, and will be set automatically for you based on the value of the -<python-debugging> feature. However, at least one Linux +<python-debugging> feature. However, at least one Linux distribution (Ubuntu Feisty Fawn) has a specially configured -python-dbg package that claims to use such a suffix.
+python-dbg package that claims to use such a suffix.
-
-

7.2   Examples

+
+

5.2   Examples

Note that in the examples below, case and especially whitespace are significant.

    @@ -229,8 +386,19 @@ using python ; +

  • If you have downloaded the Python sources and built both the +normal and the “python debugging” builds from source on +Windows, you might see:

    +
    +using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ;
+using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python_d
+  : # includes
+  : # libs
+  : <python-debugging>on ;
+
    +

  • You can set up your user-config.jam so a bjam built under Windows -can build/test both Windows and Cygwin python extensions. Just pass +can build/test both Windows and Cygwin python extensions. Just pass <target-os>cygwin in the condition parameter for the cygwin python installation:

    @@ -241,16 +409,16 @@ using python ;
 using python : : c:\\cygwin\\bin\\python2.5 : : : <target-os>cygwin ;

    when you put target-os=cygwin in your build request, it should build -with the cygwin version of python:5

    +with the cygwin version of python:5

    bjam target-os=cygwin toolset=gcc

    This is supposed to work the other way, too (targeting windows -python with a Cygwin bjam) but it seems as though the support in +python with a Cygwin bjam) but it seems as though the support in Boost.Build's toolsets for building that way is broken at the time of this writing.

    • -

  • Note that because of the way Boost.Build currently selects target +

  • Note that because of the way Boost.Build currently selects target alternatives, you might have be very explicit in your build requests. For example, given:

    @@ -269,35 +437,35 @@ bjam target-os=cygwin/python=2.4
-
-

8   Choosing a Boost.Python Library Binary

-

If—instead of letting Boost.Build construct and link withthe right +

+

6   Choosing a Boost.Python Library Binary

+

If—instead of letting Boost.Build construct and link with the right libraries automatically—you choose to use a pre-built Boost.Python library, you'll need to think about which one to link with. The Boost.Python binary comes in both static and dynamic flavors. Take -care to choose the right flavor for your application.2

-
-

8.1   The Dynamic Binary

+care to choose the right flavor for your application.2

+
+

6.1   The Dynamic Binary

The dynamic library is the safest and most-versatile choice:

  • A single copy of the library code is used by all extension -modules built with a given toolset.3
    • +modules built with a given toolset.3
  • The library contains a type conversion registry. Because one registry is shared among all extension modules, instances of a class exposed to Python in one dynamically-loaded extension module can be passed to functions exposed in another such module.
-
-

8.2   The Static Binary

+
+

6.2   The Static Binary

It might be appropriate to use the static Boost.Python library in any of the following cases:

    -
  • You are extending python and the types exposed in your +
  • You are extending python and the types exposed in your dynamically-loaded extension module don't need to be used by any other Boost.Python extension modules, and you don't care if the core library code is duplicated among them.
    • -
  • You are embedding python in your application and either:
      +
    • You are embedding python in your application and either:
      • You are targeting a Unix variant OS other than MacOS or AIX, where the dynamically-loaded extension modules can “see” the Boost.Python library symbols that are part of the executable.
        • @@ -311,22 +479,73 @@ modules (and vice-versa).
-
-

9   Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users

+
+

7   #include Issues

+
    +
  1. If you should ever have occasion to #include "python.h" +directly in a translation unit of a program using Boost.Python, +use #include "boost/python/detail/wrap_python.hpp" instead. +It handles several issues necessary for use with Boost.Python, +one of which is mentioned in the next section.
    2. +
  2. Be sure not to #include any system headers before +wrap_python.hpp. This restriction is actually imposed by +Python, or more properly, by Python's interaction with your +operating system. See +http://docs.python.org/ext/simpleExample.html for details.
    3. +
+
+
+

8   Python Debugging Builds

+

Python can be built in a special “python debugging” configuration +that adds extra checks and instrumentation that can be very useful +for developers of extension modules. The data structures used by +the debugging configuration contain additional members, so a +Python executable built with python debugging enabled cannot be +used with an extension module or library compiled without it, and +vice-versa.

+

Since pre-built “python debugging” versions of the Python +executable and libraries are not supplied with most distributions +of Python,7 and we didn't want to force our users +to build them, Boost.Build does not automatically enable python +debugging in its debug build variant (which is the default). +Instead there is a special build property called +python-debugging that, when used as a build property, will +define the right preprocessor symbols and select the right +libraries to link with.

+

On unix-variant platforms, the debugging versions of Python's data +structures will only be used if the symbol Py_DEBUG is defined. +On many windows compilers, when extension modules are built with +the preprocessor symbol _DEBUG, Python defaults to force +linking with a special debugging version of the Python DLL. Since +that symbol is very commonly used even when Python is not present, +Boost.Python temporarily undefines _DEBUG when Python.h +is #included from boost/python/detail/wrap_python.hpp - unless +BOOST_DEBUG_PYTHON is defined. The upshot is that if you want +“python debugging”and you aren't using Boost.Build, you should make +sure BOOST_DEBUG_PYTHON is defined, or python debugging will be +suppressed.

+
+
+

9   Testing Boost.Python

+

To run the full test suite for Boost.Python, invoke bjam in the +libs/python/test subdirectory of your Boost distribution.

+
+
+

10   Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users

If you are using a version of Python prior to 2.4.1 with a MinGW prior to 3.0.0 (with binutils-2.13.90-20030111-1), you will need to create a MinGW-compatible version of the Python library; the one shipped with Python will only work with a Microsoft-compatible linker. Follow the instructions in the “Non-Microsoft” section of -the “Building Extensions: Tips And Tricks” chapter in Installing +the “Building Extensions: Tips And Tricks” chapter in Installing Python Modules to create libpythonXX.a, where XX corresponds to the major and minor version numbers of your Python installation.

- +
-
[1]Note that although we tested earlier versions of +
[1]Note that although we tested earlier versions of Boost.Python with Python 2.2, and we don't think we've done anything to break compatibility, this release of Boost.Python may not have been tested with versions of Python earlier than @@ -337,24 +556,21 @@ supported.
-
[2]

Information about how to identify the +

[2]

Information about how to identify the static and dynamic builds of Boost.Python:

-

Be sure to read this section even if your compiler supports -auto-linking, as Boost.Python does not yet take advantage of -that feature.
-
[3]Because of the way most *nix platforms -share symbols among dynamically-loaded objects, I'm not -certainextension modules built with different compiler toolsets +
[3]Because of the way most *nix platforms +share symbols among dynamically-loaded objects, I'm not certain +that extension modules built with different compiler toolsets will always use different copies of the Boost.Python library when loaded into the same Python instance. Not using different libraries could be a good thing if the compilers have compatible @@ -369,7 +585,7 @@ happens.
- @@ -377,28 +593,33 @@ happens.
[4]configure overwrites the existing +
[4]configure overwrites the existing user-config.jam in your home directory (if any) after making a backup of the old version.
-
[5]Note that the <target-os>cygwin feature is +
[5]Note that the <target-os>cygwin feature is different from the <flavor>cygwin subfeature of the gcc toolset, and you might need handle both explicitly if you also have a MinGW GCC installed.
- - - - - -
[6]Create the user-config.jam file if you don't -already have one.
- + +
[7](1, 2)

Windows users, your home directory can be +

[6]

Windows users, your home directory can be found by typing:

 ECHO %HOMEDRIVE%%HOMEPATH%
-

into a Windows command prompt

+

into a command prompt window.

+
+ + + +
[7]On Unix and similar platforms, a debugging +python and associated libraries are built by adding +--with-pydebug when configuring the Python build. On +Windows, the debugging version of Python is generated by +the "Win32 Debug" target of the Visual Studio project in the +PCBuild subdirectory of a full Python source code distribution.
@@ -406,9 +627,9 @@ ECHO %HOMEDRIVE%%HOMEPATH%
-View document source. -Generated on: 2007-04-05 20:04 UTC. -Generated by Docutils from reStructuredText source. +View document source. +Generated on: 2007-07-02 13:46 UTC. +Generated by Docutils from reStructuredText source.
diff --git a/doc/building.rst b/doc/building.rst index 27bdf661..1e2c7d42 100644 --- a/doc/building.rst +++ b/doc/building.rst @@ -7,11 +7,11 @@ |(logo)|__ Boost.Python Build and Test HOWTO ============================================== -.. |(logo)| image:: ../boost.png +.. |(logo)| image:: ../../../boost.png :alt: Boost C++ Libraries: :class: boost-logo -__ ../index.htm +__ ../index.html .. section-numbering:: @@ -31,36 +31,6 @@ Boost.Python requires `Python 2.2`_ [#2.2]_ *or* |newer|__. .. _Python 2.2: http://www.python.org/2.2 __ http://www.python.org -No-Install Quickstart -===================== - -There is no need to install Boost in order to get started using -Boost.Python. These instructions use Boost.Build_ projects, -which will build those binaries as soon as they're needed. Your -first tests may take a little longer while you wait for -Boost.Python to build, but doing things this way will save you from -worrying about build intricacies like which library binaries to use -for a specific compiler configuration. - -.. Note:: Of course it's possible to use other build systems to - build Boost.Python and its extensions, but they are not - officially supported by Boost. Moreover **99% of all “I can't - build Boost.Python” problems come from trying to use another - build system**. - - If you want to use another system anyway, we suggest that you - follow these instructions, and then invoke ``bjam`` with the - ``-a -o``\ *filename* option to dump the build commands it executes - to a file, so you can see what your build system needs to do. - -1. Get Boost; see sections 1 and 2 of the Boost `Getting Started Guide`_. -2. Get the ``bjam`` build driver. See sections 5.2.1-5.2.3 of the - Boost `Getting Started Guide`_. -3. cd into the ``libs/python/test/example`` directory. - -.. _Getting Started Guide: ../../../more/getting_started/index.html - - Background ========== @@ -81,7 +51,7 @@ There are two basic models for combining C++ and Python: .. _embedding: http://www.python.org/doc/current/ext/embedding.html The key distinction between extending and embedding is the location -of C++' ``main()`` function: in the Python interpreter executable, +of the C++ ``main()`` function: in the Python interpreter executable, or in some other program, respectively. Note that even when embedding Python in another program, `extension modules are often the best way to make C/C++ functionality accessible to Python @@ -95,8 +65,254 @@ dynamically-loaded libraries with a single entry point, which means you can change them without rebuilding either the other extension modules or the executable containing ``main()``. -Getting Boost.Python Binaries -============================= +.. _quickstart: + +No-Install Quickstart +===================== + +There is no need to “install Boost” in order to get started using +Boost.Python. These instructions use Boost.Build_ projects, +which will build those binaries as soon as they're needed. Your +first tests may take a little longer while you wait for +Boost.Python to build, but doing things this way will save you from +worrying about build intricacies like which library binaries to use +for a specific compiler configuration and figuring out the right +compiler options to use yourself. + +.. .. raw:: html + +
+ +.. Note:: Of course it's possible to use other build systems to + build Boost.Python and its extensions, but they are not + officially supported by Boost. Moreover **99% of all “I can't + build Boost.Python” problems come from trying to use another + build system** without first following these instructions. + + If you want to use another system anyway, we suggest that you + follow these instructions, and then invoke ``bjam`` with the + + .. parsed-literal:: + + ``-a -o``\ *filename* + + options to dump the build commands it executes to a file, so + you can see what your alternate build system needs to do. + +.. .. raw:: html + +
+ +.. _Boost.Build: ../../../tools/build/index.html + +Basic Procedure +--------------- + +1. Get Boost; see sections 1 and 2 [`Unix/Linux`__, `Windows`__\ ] of the + Boost `Getting Started Guide`_. + + __ ../../../more/getting_started/unix-variants.html#get-boost + __ ../../../more/getting_started/windows.html#get-boost + +2. Get the ``bjam`` build driver. See section 5 [`Unix/Linux`__, + `Windows`__\ ] of the Boost `Getting Started Guide`_. + + __ ../../../more/getting_started/unix-variants.html#prepare-to-use-a-boost-library-binary + __ ../../../more/getting_started/windows.html#prepare-to-use-a-boost-library-binary + + +3. cd into the ``libs/python/example/quickstart/`` directory of your + Boost installation, which contains a small example project. + +4. Invoke ``bjam``. Replace the “\ ``stage``\ “ argument from the + example invocation from section 5 of the `Getting Started + Guide`_ with “\ ``test``\ ,“ to build all the test targets. Also add + the argument “\ ``--verbose-test``\ ” to see the output generated by + the tests when they are run. + + On Windows, your ``bjam`` invocation might look something like: + + .. parsed-literal:: + + C:\\boost_1_34_0\\…\\quickstart> **bjam toolset=msvc --verbose-test test** + + and on Unix variants, perhaps, + + .. parsed-literal:: + + ~/boost_1_34_0/…/quickstart$ **bjam toolset=gcc --verbose-test test** + +.. Admonition:: Note to Windows Users + + For the sake of concision, the rest of this guide will use + unix-style forward slashes in pathnames instead of the + backslashes with which you may be more familiar. The forward + slashes should work everywhere except in `Command Prompt`_ + windows, where you should use backslashes. + + .. _Command Prompt: ../../../more/getting_started/windows.html#command-prompt + +If you followed this procedure successfully, you will have built an +extension module called ``extending`` and tested it by running a +Python script called ``test_extending.py``. You will also have +built and run a simple application called ``embedding`` that embeds +python. + +.. _Getting Started Guide: ../../../more/getting_started/index.html + +In Case of Trouble +------------------ + +If you're seeing lots of compiler and/or linker error messages, +it's probably because Boost.Build is having trouble finding your +Python installation. You might want to pass the +``--debug-configuration`` option to ``bjam`` the first few times +you invoke it, to make sure that Boost.Build is correctly locating +all the parts of your Python installation. If it isn't, consider +`Configuring Boost.Build`_ as detailed below. + +If you're still having trouble, Someone on one of the following +mailing lists may be able to help: + +* The `Boost.Build mailing list`__ for issues related to Boost.Build +* The Python `C++ Sig`__ for issues specifically related to Boost.Python + +__ http://www.boost.org/more/mailing_lists.htm#jamboost +__ http://www.boost.org/more/mailing_lists.htm#cplussig + +In Case Everything Seemed to Work +--------------------------------- + +Rejoice! If you're new to Boost.Python, at this point it might be +a good idea to ignore build issues for a while and concentrate on +learning the library by going through the tutorial_ and perhaps +some of the `reference documentation`_, trying out what you've +learned about the API by modifying the quickstart project. + +.. _reference documentation: v2/reference.html +.. _tutorial: tutorial/index.html + +Modifying the Example Project +----------------------------- + +If you're content to keep your extension module forever in one +source file called |extending.cpp|_, inside your Boost +distribution, and import it forever as ``extending``, then you can +stop here. However, it's likely that you will want to make a few +changes. There are a few things you can do without having to learn +Boost.Build_ in depth. + +The project you just built is specified in two files in the current +directory: |boost-build.jam|_, which tells ``bjam`` where it can +find the interpreted code of the Boost build system, and +|Jamroot|_, which describes the targets you just built. These +files are heavily commented, so they should be easy to modify. +Take care, however, to preserve whitespace. Punctuation such as +``;`` will not be recognized as intended by ``bjam`` if it is not +surrounded by whitespace. + +.. |boost-build.jam| replace:: ``boost-build.jam`` +.. _boost-build.jam: ../example/quickstart/boost-build.jam + +.. |Jamroot| replace:: ``Jamroot`` +.. _Jamroot: ../example/quickstart/Jamroot + +.. |extending.cpp| replace:: ``extending.cpp`` +.. _extending.cpp: ../example/quickstart/extending.cpp + +Relocate the Project +.................... + +You'll probably want to copy this project elsewhere so you can +change it without modifying your Boost distribution. To do that, +simply + +a. copy the entire ``libs/python/example/quickstart/`` directory + into a new directory. + +b. In the new copies of |boost-build.jam|_ and |Jamroot|_, locate + the relative path near the top of the file that is clearly + marked by a comment, and edit that path so that it refers to the + same directory your Boost distribution as it referred to when + the file was in its original location in the + ``libs/python/example/quickstart/`` directory. + +For example, if you moved the project from +``/home/dave/boost_1_34_0/libs/python/example/quickstart`` to +``/home/dave/my-project``, you could change the first path in +|boost-build.jam|_ from + +.. parsed-literal:: + + **../../../..**\ /tools/build/v2 + +to + +.. parsed-literal:: + + **/home/dave/boost_1_34_0**\ /tools/build/v2 + +and change the first path in |Jamroot|_ from + +.. parsed-literal:: + + **../../../..** + +to + +.. parsed-literal:: + + **/home/dave/boost_1_34_0** + +Add New or Change Names of Existing Source Files +................................................ + +The names of additional source files involved in building your +extension module or embedding application can be listed in +|Jamroot|_ right alongside ``extending.cpp`` or ``embedding.cpp`` +respectively. Just be sure to leave whitespace around each +filename:: + + … file1.cpp file2.cpp file3.cpp … + +Naturally, if you want to change the name of a source file you can +tell Boost.Build about it by editing the name in |Jamroot|_. + +Change the Name of your Extension Module +........................................ + +The name of the extension module is determined by two things: + +1. the name in |Jamroot|_ immediately following ``python-extension``, and +2. the name passed to ``BOOST_PYTHON_MODULE`` in |extending.cpp|_. + +To change the name of the extension module from ``extending`` to +``hello``, you'd edit |Jamroot|_, changing + +.. parsed-literal:: + + python-extension **extending** : extending.cpp ; + +to + +.. parsed-literal:: + + python-extension **hello** : extending.cpp ; + +and you'd edit extending.cpp, changing + +.. parsed-literal:: + + BOOST_PYTHON_MODULE(\ **extending**\ ) + +to + +.. parsed-literal:: + + BOOST_PYTHON_MODULE(\ **hello**\ ) + +Installing Boost.Python on your System +====================================== Since Boost.Python is a separately-compiled (as opposed to `header-only`_) library, its user relies on the services of a @@ -104,25 +320,24 @@ Boost.Python library binary. .. _header-only: ../../../more/getting_started/windows.html#header-only-libraries -Installing Boost.Python on your System --------------------------------------- - -If you need a regular, installation of the Boost.Python library +If you need a regular installation of the Boost.Python library binaries on your system, the Boost `Getting Started Guide`_ will -walk you through the steps of installing one. If building binaries +walk you through the steps of creating one. If building binaries from source, you might want to supply the ``--with-python`` argument to ``bjam`` (or the ``--with-libraries=python`` argument to ``configure``), so only the Boost.Python binary will be built, rather than all the Boost binaries. + Configuring Boost.Build ======================= As described in the `Boost.Build reference manual`__, a file called -``user-config.jam`` in your home -directory [#home-dir]_ is used to -describe the build resources available to the build system. You'll -need to tell it about your Python installation. +``user-config.jam`` in your home directory [#home-dir]_ is used to +specify the tools and libraries available to the build system. You +may need to create or edit ``user-config.jam`` to tell Boost.Build +how to invoke Python, ``#include`` its headers, and link with its +libraries. __ http://www.boost.orgdoc/html/bbv2/advanced.html#bbv2.advanced.configuration @@ -135,66 +350,58 @@ __ http://www.boost.orgdoc/html/bbv2/advanced.html#bbv2.advanced.configuration were built, your ``user-config.jam`` file is probably already correct. -If you have a fairly “standard” python installation for your -platform, there's very little you need to do to describe it. -Simply having :: +If you have one fairly “standard” python installation for your +platform, you might not need to do anything special to describe it. If +you haven't configured python in ``user-config.jam`` (and you don't +specify ``--without-python`` on the Boost.Build command line), +Boost.Build will automatically execute the equivalent of :: - import toolset : using ; using python ; -in a ``user-config.jam`` file in your home directory [#home-dir]_ -should be enough. [#user-config.jam]_ For more complicated setups, -see `Advanced Configuration`_. +which automatically looks for Python in the most likely places. +However, that only happens when using the Boost.Python project file +(e.g. when referred to by another project as in the quickstart_ +method). If instead you are linking against separately-compiled +Boost.Python binaries, you should set up a ``user-config.jam`` file +with at least the minimal incantation above. -.. Note:: You might want to pass the ``--debug-configuration`` - option to ``bjam`` the first few times you invoke it, to make - sure that Boost.Build is correctly locating all the parts of - your Python installation. If it isn't, consider passing some of - the optional `Python configuration parameters`_ detailed below. - -Building an Extension Module -============================ - - -Testing -======= - - -Advanced Configuration -====================== +Python Configuration Parameters +------------------------------- If you have several versions of Python installed, or Python is installed in an unusual way, you may want to supply any or all of the following optional parameters to ``using python``. -Python Configuration Parameters -------------------------------- - version the version of Python to use. Should be in Major.Minor format, for example, ``2.3``. Do not include the subminor version (i.e. *not* ``2.5.1``). If you have multiple Python versions installed, the version will usually be the only - additional argument required. + configuration argument required. cmd-or-prefix - preferably, a command that invokes a Python - interpreter. Alternatively, the installation prefix for Python - libraries and header files. Use the alternative formulation if - there is no appropriate Python executable available. + preferably, a command that invokes a Python interpreter. + Alternatively, the installation prefix for Python libraries and + header files. Only use the alternative formulation if there is + no appropriate Python executable available. includes - the ``#include`` path for Python headers. + the ``#include`` paths for Python headers. Normally the correct + path(s) will be automatically deduced from ``version`` and/or + ``cmd-or-prefix``. libraries the path to Python library binaries. On MacOS/Darwin, - you can also pass the path of the Python framework. + you can also pass the path of the Python framework. Normally the + correct path(s) will be automatically deduced from ``version`` + and/or ``cmd-or-prefix``. condition if specified, should be a set of Boost.Build properties that are matched against the build configuration when - Boost.Build selects a Python configuration to use. + Boost.Build selects a Python configuration to use. See examples + below for details. extension-suffix A string to append to the name of extension @@ -202,10 +409,12 @@ extension-suffix don't need to use this. Usually this suffix is only used when targeting a Windows debug build of Python, and will be set automatically for you based on the value of the - ```` feature. However, at least one Linux + |python-debugging|_ feature. However, at least one Linux distribution (Ubuntu Feisty Fawn) has a specially configured `python-dbg`__ package that claims to use such a suffix. +.. |python-debugging| replace:: ```` + __ https://wiki.ubuntu.com/PyDbgBuilds @@ -247,6 +456,17 @@ significant. : intel # condition ; + +- If you have downloaded the Python sources and built both the + normal and the “\ `python debugging`_\ ” builds from source on + Windows, you might see:: + + using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python ; + using python : 2.5 : C:\\src\\Python-2.5\\PCBuild\\python_d + : # includes + : # libs + : on ; + - You can set up your user-config.jam so a bjam built under Windows can build/test both Windows and Cygwin_ python extensions. Just pass ``cygwin`` in the ``condition`` parameter @@ -290,7 +510,7 @@ __ http://zigzag.cs.msu.su/boost.build/wiki/AlternativeSelection Choosing a Boost.Python Library Binary ====================================== -If—instead of letting Boost.Build construct and link withthe right +If—instead of letting Boost.Build construct and link with the right libraries automatically—you choose to use a pre-built Boost.Python library, you'll need to think about which one to link with. The Boost.Python binary comes in both static and dynamic flavors. Take @@ -332,6 +552,64 @@ any of the following cases: use the types exposed by your statically-linked extension modules (and vice-versa). +``#include`` Issues +=================== + +1. If you should ever have occasion to ``#include "python.h"`` + directly in a translation unit of a program using Boost.Python, + use ``#include "boost/python/detail/wrap_python.hpp"`` instead. + It handles several issues necessary for use with Boost.Python, + one of which is mentioned in the next section. + +2. Be sure not to ``#include`` any system headers before + ``wrap_python.hpp``. This restriction is actually imposed by + Python, or more properly, by Python's interaction with your + operating system. See + http://docs.python.org/ext/simpleExample.html for details. + +.. _python-debugging: +.. _python debugging: + +Python Debugging Builds +======================= + +Python can be built in a special “python debugging” configuration +that adds extra checks and instrumentation that can be very useful +for developers of extension modules. The data structures used by +the debugging configuration contain additional members, so **a +Python executable built with python debugging enabled cannot be +used with an extension module or library compiled without it, and +vice-versa.** + +Since pre-built “python debugging” versions of the Python +executable and libraries are not supplied with most distributions +of Python, [#get-debug-build]_ and we didn't want to force our users +to build them, Boost.Build does not automatically enable python +debugging in its ``debug`` build variant (which is the default). +Instead there is a special build property called +``python-debugging`` that, when used as a build property, will +define the right preprocessor symbols and select the right +libraries to link with. + +On unix-variant platforms, the debugging versions of Python's data +structures will only be used if the symbol ``Py_DEBUG`` is defined. +On many windows compilers, when extension modules are built with +the preprocessor symbol ``_DEBUG``, Python defaults to force +linking with a special debugging version of the Python DLL. Since +that symbol is very commonly used even when Python is not present, +Boost.Python temporarily undefines _DEBUG when Python.h +is #included from ``boost/python/detail/wrap_python.hpp`` - unless +``BOOST_DEBUG_PYTHON`` is defined. The upshot is that if you want +“python debugging”and you aren't using Boost.Build, you should make +sure ``BOOST_DEBUG_PYTHON`` is defined, or python debugging will be +suppressed. + +Testing Boost.Python +==================== + +To run the full test suite for Boost.Python, invoke ``bjam`` in the +``libs/python/test`` subdirectory of your Boost distribution. + Notes for MinGW (and Cygwin with -mno-cygwin) GCC Users ======================================================= @@ -365,13 +643,9 @@ __ http://www.python.org/doc/current/inst/index.html __ ../../../more/getting_started/windows.html#library-naming __ ../../../more/getting_started/unix-variants.html#library-naming - Be sure to read this section even if your compiler supports - auto-linking, as Boost.Python does not yet take advantage of - that feature. - .. [#toolset-specific] Because of the way most \*nix platforms - share symbols among dynamically-loaded objects, I'm not - certainextension modules built with different compiler toolsets + share symbols among dynamically-loaded objects, I'm not certain + that extension modules built with different compiler toolsets will always use different copies of the Boost.Python library when loaded into the same Python instance. Not using different libraries could be a good thing if the compilers have compatible @@ -391,14 +665,16 @@ __ http://www.python.org/doc/current/inst/index.html toolset, and you might need handle both explicitly if you also have a MinGW GCC installed. -.. [#user-config.jam] Create the ``user-config.jam`` file if you don't - already have one. - .. [#home-dir] Windows users, your home directory can be found by typing:: ECHO %HOMEDRIVE%%HOMEPATH% - into a `Windows command prompt`__ + into a `command prompt`_ window. -__ ../../../more/getting_started/windows.html#or-build-from-the-command-prompt +.. [#get-debug-build] On Unix and similar platforms, a debugging + python and associated libraries are built by adding + ``--with-pydebug`` when configuring the Python build. On + Windows, the debugging version of Python is generated by + the "Win32 Debug" target of the Visual Studio project in the + PCBuild subdirectory of a full Python source code distribution. diff --git a/doc/index.html b/doc/index.html index d8795e92..e600366f 100644 --- a/doc/index.html +++ b/doc/index.html @@ -147,7 +147,9 @@
Frequently Asked Questions (FAQs)
-
Pyste (Boost.Python code generator)
+
Py++ Boost.Python code generator
+ +
Pyste Boost.Python code generator (no longer maintained)
Internals Documentation
@@ -175,7 +177,7 @@

-

© Copyright Dave +

© Copyright Dave Abrahams 2002-2003.

diff --git a/doc/internals.html b/doc/internals.html old mode 100755 new mode 100644 diff --git a/doc/internals.rst b/doc/internals.rst old mode 100755 new mode 100644 diff --git a/doc/news.html b/doc/news.html index 45a5b2f5..a2418951 100644 --- a/doc/news.html +++ b/doc/news.html @@ -329,7 +329,7 @@ BOOST_PYTHON_MODULE(test) 19 November 2004

-

© Copyright Dave +

© Copyright Dave Abrahams 2002-2003.

diff --git a/doc/projects.html b/doc/projects.html index 4b4b5084..6a80655c 100644 --- a/doc/projects.html +++ b/doc/projects.html @@ -375,6 +375,27 @@ application modules, including GUI and post-processing of results.

+
PolyBoRi
+ +
+

Michael Brickenstein writes:

+ +
+

The core of PolyBoRi is a C++ library, which provides + high-level data types for Boolean polynomials and monomials, + exponent vectors, as well as for the underlying polynomial + rings and subsets of the powerset of the Boolean variables. As + a unique approach, binary decision diagrams are used as + internal storage type for polynomial structures. On top of + this C++-library we provide a Python interface. This allows + parsing of complex polynomial systems, as well as sophisticated + and extendable strategies for Gröbner basis computation. + Boost.Python has helped us to create this interface in a + very clean way.

+
+
+
Rational Discovery LLC
@@ -435,11 +456,11 @@
-

Revised +

Revised - 15 July, 2003

+ 29 May, 2008

-

© Copyright Dave - Abrahams 2002-2003.

+

© Copyright Dave + Abrahams 2002-2008.

diff --git a/doc/support.html b/doc/support.html index a71e9ecd..31985634 100644 --- a/doc/support.html +++ b/doc/support.html @@ -67,7 +67,7 @@ 12 Sept, 2003

-

© Copyright Dave +

© Copyright Dave Abrahams 2003.

diff --git a/doc/tutorial/doc/Jamfile.v2 b/doc/tutorial/doc/Jamfile.v2 index 963f9346..f9b10f86 100644 --- a/doc/tutorial/doc/Jamfile.v2 +++ b/doc/tutorial/doc/Jamfile.v2 @@ -12,4 +12,5 @@ boostbook tutorial : boost.root=../../../../../.. boost.libraries=../../../../../../libs/libraries.htm + html.stylesheet=../../../../../../doc/html/boostbook.css ; diff --git a/doc/tutorial/doc/html/images/alert.png b/doc/tutorial/doc/html/images/alert.png old mode 100755 new mode 100644 diff --git a/doc/tutorial/doc/html/images/home.png b/doc/tutorial/doc/html/images/home.png old mode 100755 new mode 100644 diff --git a/doc/tutorial/doc/html/images/next.png b/doc/tutorial/doc/html/images/next.png old mode 100755 new mode 100644 diff --git a/doc/tutorial/doc/html/images/note.png b/doc/tutorial/doc/html/images/note.png old mode 100755 new mode 100644 diff --git a/doc/tutorial/doc/html/images/prev.png b/doc/tutorial/doc/html/images/prev.png old mode 100755 new mode 100644 diff --git a/doc/tutorial/doc/html/images/tip.png b/doc/tutorial/doc/html/images/tip.png old mode 100755 new mode 100644 diff --git a/doc/tutorial/doc/html/images/up.png b/doc/tutorial/doc/html/images/up.png old mode 100755 new mode 100644 diff --git a/doc/tutorial/doc/html/index.html b/doc/tutorial/doc/html/index.html index 5188c77f..5c65cb68 100644 --- a/doc/tutorial/doc/html/index.html +++ b/doc/tutorial/doc/html/index.html @@ -2,22 +2,22 @@ Chapter1.python 1.0 - - + + - + - +
-
Boost C++ Libraries Home Libraries People FAQ More
+
-
Next
+
Next

@@ -31,7 +31,7 @@

Copyright 2002-2005 Joel de Guzman, David Abrahams

-

+

Distributed under 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 ) @@ -93,10 +93,10 @@ code takes on the look of a kind of declarative interface definition language (IDL).

-

- +

+ Hello World -

+

Following C/C++ tradition, let's start with the "hello, world". A C++ Function: @@ -112,10 +112,10 @@ 

 #include <boost/python.hpp>
-using namespace boost::python;
 
-BOOST_PYTHON_MODULE(hello)
+BOOST_PYTHON_MODULE(hello_ext)
 {
+    using namespace boost::python;
     def("greet", greet);
 }
@@ -126,7 +126,7 @@ 

->>> import hello
+>>> import hello_ext
 >>> print hello.greet()
 hello, world
@@ -136,8 +136,8 @@

- Next stop... Building your Hello World - module from start to finish... + Next stop... Building your Hello World + module from start to finish...

@@ -145,10 +145,10 @@
- - + +

Last revised: May 18, 2007 at 15:46:01 GMT

Last revised: November 07, 2007 at 03:34:24 GMT
-
Next
+
Next
diff --git a/doc/tutorial/doc/html/python/embedding.html b/doc/tutorial/doc/html/python/embedding.html index 7e8250d8..89365fef 100644 --- a/doc/tutorial/doc/html/python/embedding.html +++ b/doc/tutorial/doc/html/python/embedding.html @@ -2,25 +2,25 @@ Embedding - - + + - + - +
-
Boost C++ Libraries Home Libraries People FAQ More
+
-PrevUpHomeNext +PrevUpHomeNext

@@ -39,28 +39,28 @@ a lot easier and, in a future version, it may become unnecessary to touch the Python/C API at all. So stay tuned... smiley

-

- +

+ Building embedded programs -

+

To be able to embed python into your programs, you have to link to both Boost.Python's as well as Python's own runtime library.

Boost.Python's library comes in two variants. Both are located in Boost's - /libs/python/build/bin-stage subdirectory. On Windows, the - variants are called boost_python.lib (for release builds) - and boost_python_debug.lib (for debugging). If you can't + /libs/python/build/bin-stage subdirectory. On Windows, the + variants are called boost_python.lib (for release builds) + and boost_python_debug.lib (for debugging). If you can't find the libraries, you probably haven't built Boost.Python yet. See Building and Testing on how to do this.

- Python's library can be found in the /libs subdirectory + Python's library can be found in the /libs subdirectory of your Python directory. On Windows it is called pythonXY.lib where X.Y is your major Python version number.

- Additionally, Python's /include subdirectory has to be added + Additionally, Python's /include subdirectory has to be added to your include path.

@@ -81,35 +81,37 @@ exe embedded_program # name of the executable <library-path>$(PYTHON_LIB_PATH) <find-library>$(PYTHON_EMBEDDED_LIBRARY) ; -

- +

+ Getting started -

+

Being able to build is nice, but there is nothing to build yet. Embedding the Python interpreter into one of your C++ programs requires these 4 steps:

  1. - #include <boost/python.hpp>

    + #include <boost/python.hpp>
  2. Call Py_Initialize() - to start the interpreter and create the _main_ - module.

    -
    3. + to start the interpreter and create the _main_ + module. +
  3. - Call other Python C API routines to use the interpreter.

    -
    4. + Call other Python C API routines to use the interpreter. +
-
-

-

- note Note that at this time you must - not call Py_Finalize() - to stop the interpreter. This may be fixed in a future version of boost.python. -

-
+
+ + + + + +
[Note]Note

+ Note that at this time you must not call Py_Finalize() + to stop the interpreter. This may be fixed in a future version of boost.python. +

(Of course, there can be other C++ code between all of these steps.)

@@ -117,8 +119,8 @@ exe embedded_program # name of the executable

- Now that we can embed the interpreter in - our programs, lets see how to put it to use... + Now that we can embed the interpreter in + our programs, lets see how to put it to use...

@@ -128,7 +130,7 @@ exe embedded_program # name of the executable Using the interpreter

As you probably already know, objects in Python are reference-counted. Naturally, - the PyObjects of the Python/C API are also reference-counted. + the PyObjects of the Python/C API are also reference-counted. There is a difference however. While the reference-counting is fully automatic in Python, the PythonC API requires you to do it [@http:/www.python.org/doc/current/api/refcounts.html by hand]. This is messy and especially hard to get right in the presence @@ -136,10 +138,10 @@ exe embedded_program # name of the executable and object class templates to automate the process.

-

- +

+ Running Python code -

+

Boost.python provides three related functions to run Python code from C++.

@@ -154,10 +156,10 @@ exe embedded_program # name of the executable and exec_file executes the code contained in the given file.

- The globals and locals parameters are + The globals and locals parameters are Python dictionaries containing the globals and locals of the context in which to run the code. For most intents and purposes you can use the namespace - dictionary of the _main_ + dictionary of the _main_ module for both parameters.

@@ -171,7 +173,7 @@ exe embedded_program # name of the executable first), and returns it.

- Let's import the _main_ + Let's import the _main_ module and run some Python code in its namespace: 

@@ -187,15 +189,15 @@ exe embedded_program # name of the executable
         This should create a file called 'hello.txt' in the current directory containing
         a phrase that is well-known in programming circles.
       

-

-
+

+
         Manipulating Python objects
-      

+      
 

         Often we'd like to have a class to manipulate Python objects. But we have
         already seen such a class above, and in the previous
-        section: the aptly named object class and its
-        derivatives. We've already seen that they can be constructed from a handle.
+        section: the aptly named object class and its
+        derivatives. We've already seen that they can be constructed from a handle.
         The following examples should further illustrate this fact:
       

 
@@ -205,7 +207,7 @@ exe embedded_program # name of the executable
 int five_squared = extract<int>(main_namespace["result"]);
 

 

-        Here we create a dictionary object for the _main_
+        Here we create a dictionary object for the _main_
         module's namespace. Then we assign 5 squared to the result variable and read
         this variable from the dictionary. Another way to achieve the same result
         is to use eval instead, which returns the result directly:
@@ -214,10 +216,10 @@ exe embedded_program # name of the executable
 object result = eval("5 ** 2");
 int five_squared = extract<int>(result);
-

- +

+ Exception handling -

+

If an exception occurs in the evaluation of the python expression, error_already_set is thrown: @@ -235,7 +237,7 @@ exe embedded_program # name of the executable }

- The error_already_set exception class doesn't carry any + The error_already_set exception class doesn't carry any information in itself. To find out more about the Python exception that occurred, you need to use the exception handling functions of the PythonC API in your catch-statement. @@ -266,12 +268,17 @@ exe embedded_program # name of the executable

- +
Copyright 2002-2005 Joel - de Guzman, David Abrahams
Copyright 2002-2005 Joel + de Guzman, David Abrahams

+ Distributed under 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 ) +

+
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/tutorial/doc/html/python/exception.html b/doc/tutorial/doc/html/python/exception.html index c86133c2..7a9b5c74 100644 --- a/doc/tutorial/doc/html/python/exception.html +++ b/doc/tutorial/doc/html/python/exception.html @@ -1,26 +1,26 @@ -Exception Translation - - + Exception Translation + + - + - +
-
Boost C++ Libraries Home Libraries People FAQ More
+
-PrevUpHomeNext +PrevUpHomeNext

@@ -49,12 +49,17 @@

- +
Copyright 2002-2005 Joel - de Guzman, David Abrahams
Copyright 2002-2005 Joel + de Guzman, David Abrahams

+ Distributed under 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 ) +

+
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/tutorial/doc/html/python/exposing.html b/doc/tutorial/doc/html/python/exposing.html index 3f3f1888..3f28366b 100644 --- a/doc/tutorial/doc/html/python/exposing.html +++ b/doc/tutorial/doc/html/python/exposing.html @@ -1,26 +1,26 @@ -Exposing Classes - - + Exposing Classes + + - + - +
-
Boost C++ Libraries Home Libraries People FAQ More
+
-PrevUpHomeNext +PrevUpHomeNext

@@ -64,9 +64,9 @@ }

- Here, we wrote a C++ class wrapper that exposes the member functions greet - and set. Now, after building our module as a shared library, - we may use our class World in Python. Here's a sample Python + Here, we wrote a C++ class wrapper that exposes the member functions greet + and set. Now, after building our module as a shared library, + we may use our class World in Python. Here's a sample Python session:

@@ -82,7 +82,7 @@

Constructors

- Our previous example didn't have any explicit constructors. Since World + Our previous example didn't have any explicit constructors. Since World is declared as a plain struct, it has an implicit default constructor. Boost.Python exposes the default constructor by default, which is why we were able to write @@ -106,9 +106,9 @@ };

- This time World has no default constructor; our previous + This time World has no default constructor; our previous wrapping code would fail to compile when the library tried to expose it. - We have to tell class_<World> about the constructor + We have to tell class_<World> about the constructor we want to expose instead. 

@@ -124,13 +124,13 @@
 }

- init<std::string>() exposes the constructor taking - in a std::string (in Python, constructors are spelled - ""_init_""). + init<std::string>() exposes the constructor taking + in a std::string (in Python, constructors are spelled + ""_init_"").

- We can expose additional constructors by passing more init<...>s - to the def() member function. Say for example we have + We can expose additional constructors by passing more init<...>s + to the def() member function. Say for example we have another World constructor taking in two doubles: 

@@ -142,13 +142,13 @@

On the other hand, if we do not wish to expose any constructors at all, we - may use no_init instead: + may use no_init instead: 

 class_<Abstract>("Abstract", no_init)

- This actually adds an _init_ + This actually adds an _init_ method which always raises a Python RuntimeError exception.

@@ -158,8 +158,8 @@

Data members may also be exposed to Python so that they can be accessed as attributes of the corresponding Python class. Each data member that we wish - to be exposed may be regarded as read-only - or read-write. Consider this class Var: + to be exposed may be regarded as read-only + or read-write. Consider this class Var: 

 struct Var
@@ -170,7 +170,7 @@
 };

- Our C++ Var class and its data members can be exposed + Our C++ Var class and its data members can be exposed to Python: 

@@ -191,8 +191,8 @@
 pi is around 3.14

- Note that name is exposed as read-only - while value is exposed as read-write. + Note that name is exposed as read-only + while value is exposed as read-write. 

 >>> x.name = 'e' # can't change name
@@ -224,7 +224,7 @@
 

         However, in Python attribute access is fine; it doesn't neccessarily break
         encapsulation to let users handle attributes directly, because the attributes
-        can just be a different syntax for a method call. Wrapping our Num
+        can just be a different syntax for a method call. Wrapping our Num
         class using Boost.Python:
       

 
@@ -245,8 +245,8 @@
 >>> x.rovalue = 2.17 # error!
 

 

-        Take note that the class property rovalue is exposed as
-        read-only since the rovalue
+        Take note that the class property rovalue is exposed as
+        read-only since the rovalue
         setter member function is not passed in:
       

 

@@ -273,7 +273,7 @@
 struct Derived : Base {};

- And a set of C++ functions operating on Base and Derived + And a set of C++ functions operating on Base and Derived object instances: 

@@ -282,7 +282,7 @@
 Base* factory() { return new Derived; }

- We've seen how we can wrap the base class Base: + We've seen how we can wrap the base class Base: 

 class_<Base>("Base")
@@ -290,8 +290,8 @@
     ;

- Now we can inform Boost.Python of the inheritance relationship between Derived - and its base class Base. Thus: + Now we can inform Boost.Python of the inheritance relationship between Derived + and its base class Base. Thus: 

 class_<Derived, bases<Base> >("Derived")
@@ -307,15 +307,15 @@
           member functions)
         
 
  • 
-If Base is polymorphic, Derived
+If Base is polymorphic, Derived
           objects which have been passed to Python via a pointer or reference to
-          Base can be passed where a pointer or reference to
-          Derived is expected.
+          Base can be passed where a pointer or reference to
+          Derived is expected.
         
    •

    - Now, we shall expose the C++ free functions b and d - and factory: + Now, we will expose the C++ free functions b and d + and factory: 

     def("b", b);
@@ -323,12 +323,12 @@
 def("factory", factory);

    - Note that free function factory is being used to generate - new instances of class Derived. In such cases, we use - return_value_policy<manage_new_object> to instruct - Python to adopt the pointer to Base and hold the instance - in a new Python Base object until the the Python object - is destroyed. We shall see more of Boost.Python call + Note that free function factory is being used to generate + new instances of class Derived. In such cases, we use + return_value_policy<manage_new_object> to instruct + Python to adopt the pointer to Base and hold the instance + in a new Python Base object until the the Python object + is destroyed. We will see more of Boost.Python call policies later. 

    @@ -341,9 +341,9 @@
 
    
 Class Virtual Functions
    
 
    
-        In this section, we shall learn how to make functions behave polymorphically
+        In this section, we will learn how to make functions behave polymorphically
         through virtual functions. Continuing our example, let us add a virtual function
-        to our Base class:
+        to our Base class:
       
    
 
     struct Base
@@ -356,11 +356,11 @@
         One of the goals of Boost.Python is to be minimally intrusive on an existing
         C++ design. In principle, it should be possible to expose the interface for
         a 3rd party library without changing it. It is not ideal to add anything
-        to our class Base. Yet, when
+        to our class Base. Yet, when
         you have a virtual function that's going to be overridden in Python and called
-        polymorphically from C++, we'll need to
+        polymorphically from C++, we'll need to
         add some scaffoldings to make things work properly. What we'll do is write
-        a class wrapper that derives from Base
+        a class wrapper that derives from Base
         that will unintrusively hook into the virtual functions so that a Python
         override may be called:
       
    
@@ -374,25 +374,28 @@
 };
 
    
 
    
-        Notice too that in addition to inheriting from Base,
-        we also multiply- inherited wrapper<Base> (See Wrapper).
-        The wrapper template makes
+        Notice too that in addition to inheriting from Base,
+        we also multiply- inherited wrapper<Base> (See Wrapper).
+        The wrapper template makes
         the job of wrapping classes that are meant to overridden in Python, easier.
       
    
 
    
-
    
 
    
-        alert MSVC6/7 Workaround
    
-        
     If you are using Microsoft Visual C++ 6 or 7, you have to write f as:
     
     return
-        call<int>(this->get_override("f").ptr());.
+        alert MSVC6/7 Workaround
+      
    
+
    
+        If you are using Microsoft Visual C++ 6 or 7, you have to write f as:
+      
    
+
    
+        return call<int>(this->get_override("f").ptr());.
       
    
 
    
 
    
-        BaseWrap's overridden virtual member function f
-        in effect calls the corresponding method of the Python object through get_override.
+        BaseWrap's overridden virtual member function f
+        in effect calls the corresponding method of the Python object through get_override.
       
    
 
    
-        Finally, exposing Base:
+        Finally, exposing Base:
       
    
 
     class_<BaseWrap, boost::noncopyable>("Base")
@@ -400,17 +403,25 @@
     ;
 
    
 
    
-        pure_virtual signals Boost.Python
-        that the function f is a
+        pure_virtual signals Boost.Python
+        that the function f is a
         pure virtual function.
       
    
-
    
-
    
+
    
+
+
+
+
+
+
    [Note]Note
    
 
    
-        note member function and methods
    
-        
     Python, like many object oriented languages uses the term methods. Methods correspond roughly to C++'s member functions
-      
    
-
+          member function and methods
+        
    
+
    
+          Python, like many object oriented languages uses the term methods.
+          Methods correspond roughly to C++'s member functions
+        
    
+
    
 
    
 
    
 
    
@@ -418,7 +429,7 @@
 
    
         We've seen in the previous section how classes with pure virtual functions
         are wrapped using Boost.Python's class
-        wrapper facilities. If we wish to wrap non-pure-virtual
+        wrapper facilities. If we wish to wrap non-pure-virtual
         functions instead, the mechanism is a bit different.
       
    
 
    
@@ -433,8 +444,8 @@
 };

    - had a pure virtual function f. If, however, its member - function f was not declared as pure virtual: + had a pure virtual function f. If, however, its member + function f was not declared as pure virtual: 

     struct Base
@@ -460,17 +471,20 @@
 };

    - Notice how we implemented BaseWrap::f. Now, - we have to check if there is an override for f. - If none, then we call Base::f(). + Notice how we implemented BaseWrap::f. Now, + we have to check if there is an override for f. + If none, then we call Base::f().

    -

    - alert MSVC6/7 Workaround
    -
    If you are using Microsoft Visual C++ 6 or 7, you have to rewrite - the line with the *note* as:

    return - call<char const*>(f.ptr());. + alert MSVC6/7 Workaround +

    +

    + If you are using Microsoft Visual C++ 6 or 7, you have to rewrite the line + with the *note* as: +

    +

    + return call<char const*>(f.ptr());.

    @@ -482,10 +496,10 @@ ;

    - Take note that we expose both &Base::f and &BaseWrap::default_f. Boost.Python needs to keep track - of 1) the dispatch function f and 2) the forwarding function - to its default implementation default_f. There's a special - def function for this purpose. + Take note that we expose both &Base::f and &BaseWrap::default_f. Boost.Python needs to keep track + of 1) the dispatch function f and 2) the forwarding function + to its default implementation default_f. There's a special + def function for this purpose.

    In Python, the results would be as expected: @@ -501,14 +515,14 @@ >>> derived = Derived()

    - Calling base.f(): + Calling base.f(): 

     >>> base.f()
 0

    - Calling derived.f(): + Calling derived.f(): 

     >>> derived.f()
@@ -518,17 +532,17 @@
 
    
 
    
 Class Operators/Special Functions
    
-
    
-
+
    
+
         Python Operators
-      
    
+      
 
    
         C is well known for the abundance of operators. C++ extends this to the extremes
         by allowing operator overloading. Boost.Python takes advantage of this and
         makes it easy to wrap C++ operator-powered classes.
       
    
 
    
-        Consider a file position class FilePos and a set of operators
+        Consider a file position class FilePos and a set of operators
         that take on FilePos instances:
       
    
 
    
@@ -561,16 +575,16 @@
 
    
         The code snippet above is very clear and needs almost no explanation at all.
         It is virtually the same as the operators' signatures. Just take note that
-        self refers to FilePos object. Also, not every class
-        T that you might need to interact with in an operator
-        expression is (cheaply) default-constructible. You can use other<T>()
-        in place of an actual T instance when writing "self
+        self refers to FilePos object. Also, not every class
+        T that you might need to interact with in an operator
+        expression is (cheaply) default-constructible. You can use other<T>()
+        in place of an actual T instance when writing "self
         expressions".
       
    
-
    
-
+
    
+
         Special Methods
-      
    
+      
 
    
         Python has a few more Special Methods. Boost.Python
         supports all of the standard special method names supported by real Python
@@ -596,25 +610,31 @@
 
    
         Need we say more?
       
    
-
    
-
    
-
    
-        note What is the business of operator<<? Well, the method str
-        requires the operator<<
-        to do its work (i.e. operator<< is used by the method defined by
-        def(str(self)).
-      
    
-
    
+
    
+
+
+
+
+
+
    [Note]Note
    
+          What is the business of operator<<? Well, the method str requires the operator<< to do its work (i.e. operator<<
+          is used by the method defined by def(str(self)).
+
    - +
    Copyright 2002-2005 Joel - de Guzman, David Abrahams
    Copyright 2002-2005 Joel + de Guzman, David Abrahams

    + Distributed under 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 ) +

    +
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/tutorial/doc/html/python/functions.html b/doc/tutorial/doc/html/python/functions.html index 927863d4..9e230a2b 100644 --- a/doc/tutorial/doc/html/python/functions.html +++ b/doc/tutorial/doc/html/python/functions.html @@ -2,25 +2,25 @@ Functions - - + + - - + + - +
    -
    Boost C++ Libraries Home Libraries People FAQ More
    +
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -33,10 +33,10 @@

    In this chapter, we'll look at Boost.Python powered functions in closer detail. - We shall see some facilities to make exposing C++ functions to Python safe - from potential pifalls such as dangling pointers and references. We shall also - see facilities that will make it even easier for us to expose C++ functions - that take advantage of C++ features such as overloading and default arguments. + We will see some facilities to make exposing C++ functions to Python safe from + potential pifalls such as dangling pointers and references. We will also see + facilities that will make it even easier for us to expose C++ functions that + take advantage of C++ features such as overloading and default arguments.

    @@ -49,7 +49,7 @@

    But before you do, you might want to fire up Python 2.2 or later and type - >>> import this. + >>> import this. 

    >>> import this
 The Zen of Python, by Tim Peters
@@ -68,7 +68,7 @@ In the face of ambiguity, refuse the temptation to guess.
 There should be one-- and preferably only one --obvious way to do it
 Although that way may not be obvious at first unless you're Dutch.
 Now is better than never.
-Although never is often better than right now.
+Although never is often better than right now.
 If the implementation is hard to explain, it's a bad idea.
 If the implementation is easy to explain, it may be a good idea.
 Namespaces are one honking great idea -- let's do more of those!
@@ -126,19 +126,19 @@ Namespaces are one honking great idea -- let's do more of those!
       
    
 
      
 
    1. 
-f is called passing in a reference to y
-          and a pointer to z
+f is called passing in a reference to y
+          and a pointer to z
 
      2. 
 
    2. 
-          A reference to y.x is returned
+          A reference to y.x is returned
         
      3. 
 
    3. 
-y is deleted. x is a dangling reference
+y is deleted. x is a dangling reference
         
      4. 
 
    4. 
-x.some_method() is called
+x.some_method() is called
         
      5. 
-
    5. BOOM!
      6. 
+
    6. BOOM!
      7. 
 
    
 
    
         We could copy result into a new object:
@@ -168,7 +168,7 @@ Namespaces are one honking great idea -- let's do more of those!
 };

    - Notice that the data member z is held by class Y using + Notice that the data member z is held by class Y using a raw pointer. Now we have a potential dangling pointer problem inside Y: 

    @@ -177,7 +177,7 @@ Namespaces are one honking great idea -- let's do more of those!
 >>> y.z_value() # CRASH!

    - For reference, here's the implementation of f again: + For reference, here's the implementation of f again: 

     X& f(Y& y, Z* z)
@@ -191,33 +191,33 @@ Namespaces are one honking great idea -- let's do more of those!
       
    
 
      
 
    1. 
-f is called passing in a reference to y
-          and a pointer to z
+f is called passing in a reference to y
+          and a pointer to z
 
      2. 
 
    2. 
-          A pointer to z is held by y
+          A pointer to z is held by y
 
      3. 
 
    3. 
-          A reference to y.x is returned
+          A reference to y.x is returned
         
      4. 
 
    4. 
-z is deleted. y.z is a dangling pointer
+z is deleted. y.z is a dangling pointer
         
      5. 
 
    5. 
-y.z_value() is called
+y.z_value() is called
         
      6. 
 
    6. 
-z->value() is called
+z->value() is called
         
      7. 
-
    7. BOOM!
      8. 
+
    8. BOOM!
      9. 
 
    
-
    
-
+
    
+
         Call Policies
-      
    
+      
 
    
         Call Policies may be used in situations such as the example detailed above.
-        In our example, return_internal_reference and with_custodian_and_ward
+        In our example, return_internal_reference and with_custodian_and_ward
         are our friends:
       
    
 
    @@ -226,27 +226,27 @@ Namespaces are one honking great idea -- let's do more of those!
         with_custodian_and_ward<1, 2> >());
 
    
 
    
-        What are the 1 and 2 parameters, you
+        What are the 1 and 2 parameters, you
         ask?
       
    
 
     return_internal_reference<1
 
    
 
    
-        Informs Boost.Python that the first argument, in our case Y&
-        y, is the owner of the returned reference: X&.
-        The "1" simply specifies the first argument.
-        In short: "return an internal reference X& owned
-        by the 1st argument Y& y".
+        Informs Boost.Python that the first argument, in our case Y&
+        y, is the owner of the returned reference: X&.
+        The "1" simply specifies the first argument.
+        In short: "return an internal reference X& owned
+        by the 1st argument Y& y".
       
    
 
     with_custodian_and_ward<1, 2>
 
    
 
    
         Informs Boost.Python that the lifetime of the argument indicated by ward
-        (i.e. the 2nd argument: Z* z) is dependent on the lifetime
-        of the argument indicated by custodian (i.e. the 1st argument: Y&
-        y).
+        (i.e. the 2nd argument: Z* z) is dependent on the lifetime
+        of the argument indicated by custodian (i.e. the 1st argument: Y&
+        y).
       
    
 
    
         It is also important to note that we have defined two policies above. Two
@@ -263,42 +263,46 @@ Namespaces are one honking great idea -- let's do more of those!
       
    
 
      
 
    • 
-with_custodian_and_ward
       Ties lifetimes
+with_custodian_and_ward: Ties lifetimes
           of the arguments
         
      • 
 
    • 
-with_custodian_and_ward_postcall
      
-          Ties lifetimes of the arguments and results
+with_custodian_and_ward_postcall: Ties
+          lifetimes of the arguments and results
         
      • 
 
    • 
-return_internal_reference
       Ties lifetime
+return_internal_reference: Ties lifetime
           of one argument to that of result
         
      • 
 
    • 
-return_value_policy<T> with T one of:
      
+return_value_policy<T> with T one of:
        
+
      • 
+reference_existing_object: naive (dangerous)
+              approach
+            
        • 
+
      • 
+copy_const_reference: Boost.Python
+              v1 approach
+            
        • 
+
      • 
+copy_non_const_reference:
+            
        • 
+
      • 
+manage_new_object: Adopt a pointer
+              and hold the instance
+            
        • 
+
      
 
      • 
-
    • 
-reference_existing_object
       naive
-          (dangerous) approach
-        
      • 
-
    • 
-copy_const_reference
       Boost.Python
-          v1 approach
-        
      • 
-
    • 
-copy_non_const_reference
      
-
      • 
-
    • 
-manage_new_object
       Adopt a pointer
-          and hold the instance
-        
      • 
 
    
 
    
-
    
 
    
-        smiley Remember the Zen, Luke:
    
-        
     "Explicit is better than implicit"
     "In the face
-        of ambiguity, refuse the temptation to guess"
    
+        smiley Remember the Zen, Luke:
+      
    
+
    
+        "Explicit is better than implicit"
+      
    
+
    
+        "In the face of ambiguity, refuse the temptation to guess"
    @@ -338,7 +342,7 @@ Namespaces are one honking great idea -- let's do more of those! };

    - Class X has 4 overloaded functions. We shall start by introducing some member + Class X has 4 overloaded functions. We will start by introducing some member function pointer variables: 

    @@ -362,21 +366,21 @@ Namespaces are one honking great idea -- let's do more of those!
 Default Arguments

    Boost.Python wraps (member) function pointers. Unfortunately, C++ function - pointers carry no default argument info. Take a function f + pointers carry no default argument info. Take a function f with default arguments: 

     int f(int, double = 3.14, char const* = "hello");

    - But the type of a pointer to the function f has no information + But the type of a pointer to the function f has no information about its default arguments: 

     int(*g)(int,double,char const*) = f;    // defaults lost!

    - When we pass this function pointer to the def function, + When we pass this function pointer to the def function, there is no way to retrieve the default arguments: 

    @@ -410,10 +414,10 @@ Namespaces are one honking great idea -- let's do more of those!
           are overloaded with a common sequence of initial arguments
    -

    - +

    + BOOST_PYTHON_FUNCTION_OVERLOADS -

    +

    Boost.Python now has a way to make it easier. For instance, given a function:

    @@ -431,19 +435,19 @@ Namespaces are one honking great idea -- let's do more of those!

    will automatically create the thin wrappers for us. This macro will create - a class foo_overloads that can be passed on to def(...). + a class foo_overloads that can be passed on to def(...). The third and fourth macro argument are the minimum arguments and maximum - arguments, respectively. In our foo function the minimum - number of arguments is 1 and the maximum number of arguments is 4. The def(...) + arguments, respectively. In our foo function the minimum + number of arguments is 1 and the maximum number of arguments is 4. The def(...) function will automatically add all the foo variants for us: 

     def("foo", foo, foo_overloads());
    -

    - +

    + BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS -

    +

    Objects here, objects there, objects here there everywhere. More frequently than anything else, we need to expose member functions of our classes to @@ -452,7 +456,7 @@ Namespaces are one honking great idea -- let's do more of those! play. Another macro is provided to make this a breeze.

    - Like BOOST_PYTHON_FUNCTION_OVERLOADS, BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS + Like BOOST_PYTHON_FUNCTION_OVERLOADS, BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS may be used to automatically create the thin wrappers for wrapping member functions. Let's have an example:

    @@ -473,11 +477,11 @@ Namespaces are one honking great idea -- let's do more of those! BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(george_overloads, wack_em, 1, 3)

    - will generate a set of thin wrappers for george's wack_em + will generate a set of thin wrappers for george's wack_em member function accepting a minimum of 1 and a maximum of 3 arguments (i.e. the third and fourth macro argument). The thin wrappers are all enclosed - in a class named george_overloads that can then be used - as an argument to def(...): + in a class named george_overloads that can then be used + as an argument to def(...): 

     .def("wack_em", &george::wack_em, george_overloads());
@@ -486,13 +490,13 @@ Namespaces are one honking great idea -- let's do more of those!
         See the overloads
         reference for details.
       
    
-
    
-
+
    
+
         init and optional
-      
    
+      
 
    
         A similar facility is provided for class constructors, again, with default
-        arguments or a sequence of overloads. Remember init<...>?
+        arguments or a sequence of overloads. Remember init<...>?
         For example, given a class X with a constructor:
       
    
 
    @@ -509,7 +513,7 @@ Namespaces are one honking great idea -- let's do more of those!
 .def(init<int, optional<char, std::string, double> >())
 
    
 
    
-        Notice the use of init<...> and optional<...>
+        Notice the use of init<...> and optional<...>
         to signify the default (optional arguments).
    @@ -517,8 +521,8 @@ Namespaces are one honking great idea -- let's do more of those!

    Auto-Overloading

    - It was mentioned in passing in the previous section that BOOST_PYTHON_FUNCTION_OVERLOADS - and BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS can also be + It was mentioned in passing in the previous section that BOOST_PYTHON_FUNCTION_OVERLOADS + and BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS can also be used for overloaded functions and member functions with a common sequence of initial arguments. Here is an example:

    @@ -560,24 +564,24 @@ Namespaces are one honking great idea -- let's do more of those! Notice though that we have a situation now where we have a minimum of zero (0) arguments and a maximum of 3 arguments.

    -

    - +

    + Manual Wrapping -

    +

    - It is important to emphasize however that the overloaded - functions must have a common sequence of initial arguments. Otherwise, + It is important to emphasize however that the overloaded + functions must have a common sequence of initial arguments. Otherwise, our scheme above will not work. If this is not the case, we have to wrap our functions manually.

    Actually, we can mix and match manual wrapping of overloaded functions and - automatic wrapping through BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS - and its sister, BOOST_PYTHON_FUNCTION_OVERLOADS. Following + automatic wrapping through BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS + and its sister, BOOST_PYTHON_FUNCTION_OVERLOADS. Following up on our example presented in the section on overloading, since the first 4 overload functins have a common sequence - of initial arguments, we can use BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS - to automatically wrap the first three of the defs and + of initial arguments, we can use BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS + to automatically wrap the first three of the defs and manually wrap just the last. Here's how we'll do this: 

    @@ -601,12 +605,17 @@ Namespaces are one honking great idea -- let's do more of those!
    - +
    Copyright 2002-2005 Joel - de Guzman, David Abrahams
    Copyright 2002-2005 Joel + de Guzman, David Abrahams

    + Distributed under 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 ) +

    +
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/tutorial/doc/html/python/hello.html b/doc/tutorial/doc/html/python/hello.html index 062e5c29..99c089ec 100644 --- a/doc/tutorial/doc/html/python/hello.html +++ b/doc/tutorial/doc/html/python/hello.html @@ -1,84 +1,71 @@ -Building Hello World - - + Building Hello World + + - + - +
    -
    Boost C++ Libraries Home Libraries People FAQ More
    +
    -PrevUpHomeNext +PrevUpHomeNext

    Building Hello World

    -

    - +

    + From Start To Finish -

    +

    Now the first thing you'd want to do is to build the Hello World module and - try it for yourself in Python. In this section, we shall outline the steps - necessary to achieve that. We shall use the build tool that comes bundled with - every boost distribution: bjam. + try it for yourself in Python. In this section, we will outline the steps necessary + to achieve that. We will use the build tool that comes bundled with every boost + distribution: bjam.

    -
    -

    +
    + + + + + +
    [Note]Note

    - note Building without bjam
    -
    Besides bjam, there are of course other ways to get your module built. - What's written here should not be taken as "the one and only way". - There are of course other build tools apart from bjam.
    -
    Take note however that the preferred build tool for Boost.Python is - bjam. There are so many ways to set up the build incorrectly. Experience shows - that 90% of the "I can't build Boost.Python" problems come from people - who had to use a different tool. -

    - + Building without bjam +

    - We shall skip over the details. Our objective will be to simply create the - hello world module and run it in Python. For a complete reference to building - Boost.Python, check out: building.html. - After this brief bjam tutorial, we should have built two - DLLs: -

    -
      -
    • - boost_python.dll -
      • -
    • - hello.pyd -
      • -
    + Besides bjam, there are of course other ways to get your module built. What's + written here should not be taken as "the one and only way". There + are of course other build tools apart from bjam. +

    - if you are on Windows, and -

    -
      -
    • - libboost_python.so -
      • -
    • - hello.so -
      • -
    + Take note however that the preferred build tool for Boost.Python is bjam. + There are so many ways to set up the build incorrectly. Experience shows + that 90% of the "I can't build Boost.Python" problems come from + people who had to use a different tool. +

    +

    - if you are on Unix. + We will skip over the details. Our objective will be to simply create the hello + world module and run it in Python. For a complete reference to building Boost.Python, + check out: building.html. After + this brief bjam tutorial, we should have built the DLLs + and run a python program using the extension.

    - The tutorial example can be found in the directory: libs/python/example/tutorial. + The tutorial example can be found in the directory: libs/python/example/tutorial. There, you can find:

      @@ -86,75 +73,44 @@ hello.cpp
    • - Jamfile + hello.py +
      • +
    • + Jamroot

    - The hello.cpp file is our C++ hello world example. The - Jamfile is a minimalist bjam script - that builds the DLLs for us. + The hello.cpp file is our C++ hello world example. The + Jamroot is a minimalist bjam script + that builds the DLLs for us. Finally, hello.py is our Python + program that uses the extension in hello.cpp.

    Before anything else, you should have the bjam executable in your boost directory - or somewhere in your path such that bjam can be executed + or somewhere in your path such that bjam can be executed in the command line. Pre-built Boost.Jam executables are available for most platforms. The complete list of Bjam executables can be found here.

    -

    - +

    + Let's Jam! -

    +

    jam

    - Here is our minimalist Jamfile: -

    -
    # This is the top of our own project tree
-project-root ;
-
-import python ;
-
-extension hello                     # Declare a Python extension called hello
-:   hello.cpp                       # source
-    # requirements and dependencies for Boost.Python extensions
-    <template>@boost/libs/python/build/extension
-    ;
-
    -

    - First, we need to specify our location. You may place your project anywhere. - project-root allows you to do that. -

    -
    project-root ;
-
    -

    - By doing so, you'll need a Jamrules file. Simply copy the one in the example/tutorial directory - and tweak the path-global BOOST_ROOT to where your boost - root directory is. The file has detailed - instructions you can follow. + Here is our minimalist + Jamroot file. Simply copy the file and tweak use-project boost + to where your boost root directory is and your OK.

    - Then we will import the definitions needed by Python modules: + The comments contained in the Jamrules file above should be sufficient to get + you going.

    -
    import python ;
-
    -

    - Finally we declare our hello extension: -

    -
    extension hello                     # Declare a Python extension called hello
-:   hello.cpp                       # source
-
-    # requirements and dependencies for Boost.Python extensions
-    <template>@boost/libs/python/build/extension
-    ;
-
    -

    - The last part tells BJam that we are depending on the Boost Python Library. -

    -

    - +

    + Running bjam -

    +

    bjam is run using your operating system's command line interpreter. @@ -169,124 +125,66 @@ extension hello # Declare a Python extension called hello

    - Make sure that the environment is set so that we can invoke the C++ compiler. - With MSVC, that would mean running the Vcvars32.bat batch - file. For instance: + A file called user-config.jam in your home directory is used to configure your + tools. In Windows, your home directory can be found by typing:

    -
    C:\Program Files\Microsoft Visual Studio .NET 2003\Common7\Tools\vsvars32.bat
+
    ECHO %HOMEDRIVE%%HOMEPATH%
 
    
 
    
-      Some environment variables will have to be setup for proper building of our
-      Python modules. Example:
+      into a command prompt window. Your file should at least have the rules for
+      your compiler and your python installation. A specific example of this on Windows
+      would be:
     
    
-
    set PYTHON_ROOT=c:/dev/tools/python
-set PYTHON_VERSION=2.2
+
    #  MSVC configuration
+using msvc : 8.0 ;
+
+#  Python configuration
+using python : 2.4 : C:/dev/toolsPython ;
 
    
 
    
-      The above assumes that the Python installation is in c:/dev/tools/python
-      and that we are using Python version 2.2. You'll have to tweak these appropriately.
-    
    
-
    
-
    
-
    
-      tip Be sure not to include a third number, e.g. not "2.2.1", even if that's the version you
-      have.
-    
    
-
    
-
    
-      Take note that you may also do that through the Jamrules file we put in our
-      project as detailed above. The file has detailed
-      instructions you can follow.
+      The first rule tells Bjam to use the MSVC 8.0 compiler and associated tools.
+      The second rule provides information on Python, its version and where it is
+      located. The above assumes that the Python installation is in C:/dev/tools/Python/.
+      If you have one fairly "standard" python installation for your platform,
+      you might not need to do this.
     
    
 
    
-      Now we are ready... Be sure to cd to libs/python/example/tutorial
-      where the tutorial "hello.cpp" and the "Jamfile"
+      Now we are ready... Be sure to cd to libs/python/example/tutorial
+      where the tutorial "hello.cpp" and the "Jamroot"
       is situated.
     
    
 
    
       Finally:
     
    
 
    -bjam -sTOOLS=vc-7_1
+bjam
 
    
-
    
-      We are again assuming that we are using Microsoft Visual C++ version 7.1. If
-      not, then you will have to specify the appropriate tool. See Building
-      Boost Libraries for further details.
-    
    
 
    
       It should be building now:
     
    
 
    cd C:\dev\boost\libs\python\example\tutorial
-bjam -sTOOLS=msvc
+bjam
 ...patience...
-...found 1703 targets...
-...updating 40 targets...
+...found 1101 targets...
+...updating 35 targets...
 
    
 
    
       And so on... Finally:
     
    
-
    Creating library bin\boost\libs\python\build\boost_python.dll\vc-7_1\debug\th
-reading-multi\boost_python.lib and object bin\boost\libs\python\build\boost_pyth
-on.dll\vc-7_1\debug\threading-multi\boost_python.exp
-vc-C++ bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.obj
-hello.cpp
-vc-Link bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.pyd bin\tutori
-al\hello.pyd\vc-7_1\debug\threading-multi\hello.lib
-   Creating library bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.li
-b and object bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.exp
-...updated 31 targets...
-
    
-
    
-      If all is well, you should now have:
-    
    
-
      
-
    • 
-        boost_python.dll
-      
      • 
-
    • 
-        hello.pyd
-      
      • 
-
    
-
    
-      if you are on Windows, and
-    
    
-
      
-
    • 
-        libboost_python.so
-      
      • 
-
    • 
-        hello.so
-      
      • 
-
    
-
    
-      if you are on Unix.
-    
    
-
    
-      boost_python.dll and hello.pyd can be
-      found somewhere in your project's bin directory. After a
-      successful build, you make it possible for the system to find boost_python.dll
-      or libboost_python.so (usually done with LD_LIBRARY_PATH, DYLD_LIBRARY_PATH,
-      or some other variable on *nix and with PATH on Windows) and for Python to
-      find the hello module (Done with PYTHONPATH on all systems.)
-    
    
-
    
-      You may now fire up Python and run our hello module:
-    
    
-
    
-    
    
-
    ->>> import hello
->>> print hello.greet()
-hello, world
+
    Creating library path-to-boost_python.dll
+   Creating library path-to-'''hello_ext'''.exp
+**passed** ... hello.test
+...updated 35 targets...
 
    
 
    
+      Or something similar. If all is well, you should now have built the DLLs and
+      run the Python program.
     
    
 
    
 
    
         
    
 
    
-          There you go... Have fun!
+          There you go... Have fun!
         
    
 
    
       
    
@@ -294,12 +192,17 @@ b and object bin\tutorial\hello.pyd\vc-7_1\debug\threading-multi\hello.exp
 
    
 
-
+
    
 Copyright  2002-2005 Joel
-      de Guzman, David Abrahams
    Copyright  2002-2005 Joel
+      de Guzman, David Abrahams
    
+        Distributed under 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 )
+      
    
+
    		
 
    
 
    
 
    
-PrevUpHomeNext
+PrevUpHomeNext
 
    
 
 
diff --git a/doc/tutorial/doc/html/python/iterators.html b/doc/tutorial/doc/html/python/iterators.html
index a937c377..ad012f8f 100644
--- a/doc/tutorial/doc/html/python/iterators.html
+++ b/doc/tutorial/doc/html/python/iterators.html
@@ -2,25 +2,25 @@
 
 
 Iterators
-
-
+
+
 
 
 
-
+
 
 
-
+
    
-
    
 Boost C++ Libraries
 Home
 Libraries
 People
 FAQ
 More
    
+
 
    
 
    
-PrevUpHomeNext
+PrevUpHomeNext
 
    
 
    
 
    
@@ -30,7 +30,7 @@
       iterators, but these are two very different beasts.
     
    
 
    
-      C++ iterators:
+      C++ iterators:
     
    
 
      
 
    • 
@@ -45,7 +45,7 @@
       
      • 
 
    
 
    
-      Python Iterators:
+      Python Iterators:
     
    
 
      
 
    • 
@@ -59,8 +59,8 @@
       
      • 
 
    
 
    
-      The typical Python iteration protocol: for y
-      in x... is as follows:
+      The typical Python iteration protocol: for y
+      in x... is as follows:
     
    
 
    
     
    
@@ -74,7 +74,7 @@
 
    
 
    
       Boost.Python provides some mechanisms to make C++ iterators play along nicely
-      as Python iterators. What we need to do is to produce appropriate __iter__ function from C++ iterators that
+      as Python iterators. What we need to do is to produce appropriate __iter__ function from C++ iterators that
       is compatible with the Python iteration protocol. For example:
     
    
 
    
@@ -91,7 +91,7 @@
 .def("__iter__", iterator<vector<int> >())
 
    
 
    
-      range
+      range
     
    
 
    
       We can create a Python savvy iterator using the range function:
@@ -119,14 +119,14 @@

    - iterator + iterator

    • iterator<T, Policies>()

    - Given a container T, iterator is a shortcut that simply - calls range with &T::begin, &T::end. + Given a container T, iterator is a shortcut that simply + calls range with &T::begin, &T::end.

    Let's put this into action... Here's an example from some hypothetical bogon @@ -152,14 +152,14 @@ .property("bogons", range(&F::b_begin, &F::b_end));

    - stl_input_iterator + stl_input_iterator

    So far, we have seen how to expose C++ iterators and ranges to Python. Sometimes we wish to go the other way, though: we'd like to pass a Python sequence to an STL algorithm or use it to initialize an STL container. We need to make - a Python iterator look like an STL iterator. For that, we use stl_input_iterator<>. - Consider how we might implement a function that exposes std::list<int>::assign() to Python: + a Python iterator look like an STL iterator. For that, we use stl_input_iterator<>. + Consider how we might implement a function that exposes std::list<int>::assign() to Python:

    @@ -178,7 +178,7 @@ ;

    - Now in Python, we can assign any integer sequence to list_int + Now in Python, we can assign any integer sequence to list_int objects:

    @@ -190,12 +190,17 @@

    - +
    Copyright 2002-2005 Joel - de Guzman, David Abrahams
    Copyright 2002-2005 Joel + de Guzman, David Abrahams

    + Distributed under 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 ) +

    +
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/tutorial/doc/html/python/object.html b/doc/tutorial/doc/html/python/object.html index e198cca7..6f8920ab 100644 --- a/doc/tutorial/doc/html/python/object.html +++ b/doc/tutorial/doc/html/python/object.html @@ -1,26 +1,26 @@ -Object Interface - - + Object Interface + + - +
    -
    Boost C++ Libraries Home Libraries People FAQ More
    +
    -PrevUpHomeNext +PrevUpHomeNext

    @@ -35,13 +35,13 @@ Python is dynamically typed, unlike C++ which is statically typed. Python variables may hold an integer, a float, list, dict, tuple, str, long etc., among other things. In the viewpoint of Boost.Python and C++, these Pythonic variables - are just instances of class object. We shall see in this + are just instances of class object. We will see in this chapter how to deal with Python objects.

    As mentioned, one of the goals of Boost.Python is to provide a bidirectional mapping between C++ and Python while maintaining the Python feel. Boost.Python - C++ objects are as close as possible to Python. This should + C++ objects are as close as possible to Python. This should minimize the learning curve significantly.

    @@ -51,10 +51,10 @@

    Basic Interface

    - Class object wraps PyObject*. All the - intricacies of dealing with PyObjects such as managing - reference counting are handled by the object class. C++ - object interoperability is seamless. Boost.Python C++ objects + Class object wraps PyObject*. All the + intricacies of dealing with PyObjects such as managing + reference counting are handled by the object class. C++ + object interoperability is seamless. Boost.Python C++ objects can in fact be explicitly constructed from any C++ object.

    @@ -99,7 +99,7 @@

    Derived Object types

    - Boost.Python comes with a set of derived object types + Boost.Python comes with a set of derived object types corresponding to that of Python's:

      @@ -123,32 +123,32 @@

    - These derived object types act like real Python types. + These derived object types act like real Python types. For instance: 

     str(1) ==> "1"

    - Wherever appropriate, a particular derived object has - corresponding Python type's methods. For instance, dict - has a keys() method: + Wherever appropriate, a particular derived object has + corresponding Python type's methods. For instance, dict + has a keys() method: 

     d.keys()

    - make_tuple is provided for declaring tuple literals. + make_tuple is provided for declaring tuple literals. Example: 

     make_tuple(123, 'D', "Hello, World", 0.0);

    - In C++, when Boost.Python objects are used as arguments + In C++, when Boost.Python objects are used as arguments to functions, subtype matching is required. For example, when a function - f, as declared below, is wrapped, it will only accept - instances of Python's str type and subtypes. + f, as declared below, is wrapped, it will only accept + instances of Python's str type and subtypes. 

     void f(str name)
@@ -172,18 +172,15 @@
 object msg = "%s is bigger than %s" % make_tuple(NAME,name);

    - Demonstrates that you can write the C++ equivalent of "format" - % x,y,z in Python, which is useful since there's no easy way to + Demonstrates that you can write the C++ equivalent of "format" + % x,y,z in Python, which is useful since there's no easy way to do that in std C++.

    -
    -

    -

    - alert Beware the common pitfall +

    + alert Beware the common pitfall of forgetting that the constructors of most of Python's mutable types make copies, just as in Python. -

    -
    +

    Python:

    @@ -198,12 +195,12 @@ dict d(x.attr("__dict__")); // copies x.__dict__ d['whatever'] = 3; // modifies the copy -

    - +

    + class_<T> as objects -

    +

    - Due to the dynamic nature of Boost.Python objects, any class_<T> + Due to the dynamic nature of Boost.Python objects, any class_<T> may also be one of these types! The following code snippet wraps the class (type) object.

    @@ -225,15 +222,15 @@ Extracting C++ objects

    At some point, we will need to get C++ values out of object instances. This - can be achieved with the extract<T> function. Consider + can be achieved with the extract<T> function. Consider the following: 

     double x = o.attr("length"); // compile error

    - In the code above, we got a compiler error because Boost.Python object - can't be implicitly converted to doubles. Instead, what + In the code above, we got a compiler error because Boost.Python object + can't be implicitly converted to doubles. Instead, what we wanted to do above can be achieved by writing: 

    @@ -243,14 +240,14 @@

    The first line attempts to extract the "length" attribute of the - Boost.Python object. The second line attempts to extract - the Vec2 object from held by the Boost.Python object. + Boost.Python object. The second line attempts to extract + the Vec2 object from held by the Boost.Python object.

    Take note that we said "attempt to" above. What if the Boost.Python - object does not really hold a Vec2 + object does not really hold a Vec2 type? This is certainly a possibility considering the dynamic nature of Python - objects. To be on the safe side, if the C++ type can't + objects. To be on the safe side, if the C++ type can't be extracted, an appropriate exception is thrown. To avoid an exception, we need to test for extractibility:

    @@ -260,7 +257,7 @@ Vec2& v = x(); ...

    - tip The astute reader might have noticed that the extract<T> + tip The astute reader might have noticed that the extract<T> facility in fact solves the mutable copying problem: 

    @@ -273,8 +270,8 @@
 Enums

    Boost.Python has a nifty facility to capture and wrap C++ enums. While Python - has no enum type, we'll often want to expose our C++ enums - to Python as an int. Boost.Python's enum facility makes + has no enum type, we'll often want to expose our C++ enums + to Python as an int. Boost.Python's enum facility makes this easy while taking care of the proper conversions from Python's dynamic typing to C++'s strong static typing (in C++, ints cannot be implicitly converted to enums). To illustrate, given a C++ enum: @@ -293,19 +290,26 @@

    can be used to expose to Python. The new enum type is created in the current - scope(), which is usually the current module. The snippet - above creates a Python class derived from Python's int + scope(), which is usually the current module. The snippet + above creates a Python class derived from Python's int type which is associated with the C++ type passed as its first parameter.

    -
    -

    +
    + + + + + +
    [Note]Note

    - note what is a scope?
    -
    The scope is a class that has an associated global Python object which - controls the Python namespace in which new extension classes and wrapped - functions will be defined as attributes. Details can be found here. -

    - + what is a scope? +

    +

    + The scope is a class that has an associated global Python object which + controls the Python namespace in which new extension classes and wrapped + functions will be defined as attributes. Details can be found here. +

    +

    You can access those values in Python as

    @@ -337,12 +341,17 @@
    - +
    Copyright 2002-2005 Joel - de Guzman, David Abrahams
    Copyright 2002-2005 Joel + de Guzman, David Abrahams

    + Distributed under 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 ) +

    +
    -PrevUpHomeNext +PrevUpHomeNext
    diff --git a/doc/tutorial/doc/html/python/techniques.html b/doc/tutorial/doc/html/python/techniques.html index 4b8971ec..8598e927 100644 --- a/doc/tutorial/doc/html/python/techniques.html +++ b/doc/tutorial/doc/html/python/techniques.html @@ -1,25 +1,25 @@ -General Techniques - - + General Techniques + + - + - +
    -
    Boost C++ Libraries Home Libraries People FAQ More
    +
    -PrevUpHome +PrevUpHome

    @@ -50,7 +50,7 @@

    We have a C++ library that works with sounds: reading and writing various formats, applying filters to the sound data, etc. It is named (conveniently) - sounds. Our library already has a neat C++ namespace hierarchy, + sounds. Our library already has a neat C++ namespace hierarchy, like so: 

    @@ -93,18 +93,21 @@
 }

    - Compiling these files will generate the following Python extensions: core.pyd, - io.pyd and filters.pyd. + Compiling these files will generate the following Python extensions: core.pyd, + io.pyd and filters.pyd.

    -
    -

    -

    - note The extension .pyd is used for python - extension modules, which are just shared libraries. Using the default for - your system, like .so for Unix and .dll - for Windows, works just as well. -

    -
    +
    + + + + + +
    [Note]Note

    + The extension .pyd is used for python extension modules, + which are just shared libraries. Using the default for your system, like + .so for Unix and .dll for Windows, + works just as well. +

    Now, we create this directory structure for our Python package:

    @@ -115,12 +118,12 @@ io.pyd

    - The file __init__.py is what tells Python that the directory - sounds/ is actually a Python package. It can be a empty + The file __init__.py is what tells Python that the directory + sounds/ is actually a Python package. It can be a empty file, but can also perform some magic, that will be shown later.

    - Now our package is ready. All the user has to do is put sounds + Now our package is ready. All the user has to do is put sounds into his PYTHONPATH and fire up the interpreter:

    @@ -159,7 +162,7 @@

    Note that we added an underscore to the module name. The filename will have - to be changed to _core.pyd as well, and we do the same + to be changed to _core.pyd as well, and we do the same to the other extension modules. Now, we change our package hierarchy like so:

    @@ -187,11 +190,11 @@ >>> sounds.core._core.foo(...)

    - which is not what we want. But here enters the __init__.py - magic: everything that is brought to the __init__.py namespace + which is not what we want. But here enters the __init__.py + magic: everything that is brought to the __init__.py namespace can be accessed directly by the user. So, all we have to do is bring the - entire namespace from _core.pyd to core/__init__.py. - So add this line of code to soundscore__init__.py: + entire namespace from _core.pyd to core/__init__.py. + So add this line of code to soundscore__init__.py: 

     from _core import *
@@ -208,10 +211,10 @@
         with the additional benefit that we can easily add pure Python functions
         to any module, in a way that the user can't tell the difference between a
         C++ function and a Python function. Let's add a pure
-        Python function, echo_noise, to the filters
-        package. This function applies both the echo and noise
-        filters in sequence in the given sound object. We create
-        a file named sounds/filters/echo_noise.py and code our
+        Python function, echo_noise, to the filters
+        package. This function applies both the echo and noise
+        filters in sequence in the given sound object. We create
+        a file named sounds/filters/echo_noise.py and code our
         function:
       
    
 
    @@ -222,14 +225,14 @@
     return s
 
    
 
    
-        Next, we add this line to soundsfilters__init__.py:
+        Next, we add this line to soundsfilters__init__.py:
       
    
 
     from echo_noise import echo_noise
 
    
 
    
         And that's it. The user now accesses this function like any other function
-        from the filters package:
+        from the filters package:
       
    
 
     >>> import sounds.filters
@@ -263,7 +266,7 @@
       
    
 
    
         We can do the same with classes that were wrapped with Boost.Python. Suppose
-        we have a class point in C++:
+        we have a class point in C++:
       
    
 
    
       
    
@@ -277,7 +280,7 @@
 
    
 
    
         If we are using the technique from the previous session, Creating
-        Packages, we can code directly into geom/__init__.py:
+        Packages, we can code directly into geom/__init__.py:
       
    
 
    
       
    
@@ -292,7 +295,7 @@
 point.__str__ = point_str

    - All point instances created from C++ will + All point instances created from C++ will also have this member function! This technique has several advantages:

      @@ -391,7 +394,7 @@ }

      - Now you create a file main.cpp, which contains the BOOST_PYTHON_MODULE + Now you create a file main.cpp, which contains the BOOST_PYTHON_MODULE macro, and call the various export functions inside it. 

      @@ -427,33 +430,43 @@
         exporting it to Python at the same time: changes in a class will only demand
         the compilation of a single cpp, instead of the entire wrapper code.
       
      
-
      
-
      
-
      
-        note If you're exporting your classes with Pyste,
-        take a look at the --multiple option, that generates the
-        wrappers in various files as demonstrated here.
-      
      
-
      
-
      
-
      
-
      
-        note This method is useful too if you are getting the error
-        message "fatal error C1204:Compiler limit:internal structure
-        overflow" when compiling a large source file, as explained
-        in the FAQ.
-      
      
-
      
+
      
+
+
+
+
+
+
      [Note]Note
      
+          If you're exporting your classes with Pyste,
+          take a look at the --multiple option, that generates
+          the wrappers in various files as demonstrated here.
+        
      
+
      
+
+
+
+
+
+
      [Note]Note
      
+          This method is useful too if you are getting the error message "fatal
+          error C1204:Compiler limit:internal structure overflow"
+          when compiling a large source file, as explained in the FAQ.
+

    - +
    Copyright 2002-2005 Joel - de Guzman, David Abrahams
    Copyright 2002-2005 Joel + de Guzman, David Abrahams

    + Distributed under 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 ) +

    +
    -PrevUpHome +PrevUpHome
    diff --git a/doc/tutorial/doc/tutorial.qbk b/doc/tutorial/doc/tutorial.qbk index 13a2222a..9bd3c3fb 100644 --- a/doc/tutorial/doc/tutorial.qbk +++ b/doc/tutorial/doc/tutorial.qbk @@ -49,10 +49,10 @@ Function: can be exposed to Python by writing a Boost.Python wrapper: #include - using namespace boost::python; - BOOST_PYTHON_MODULE(hello) + BOOST_PYTHON_MODULE(hello_ext) { + using namespace boost::python; def("greet", greet); } @@ -61,7 +61,7 @@ resulting DLL is now visible to Python. Here's a sample Python session: [python] - >>> import hello + >>> import hello_ext >>> print hello.greet() hello, world @@ -75,43 +75,39 @@ resulting DLL is now visible to Python. Here's a sample Python session: [h2 From Start To Finish] Now the first thing you'd want to do is to build the Hello World module and -try it for yourself in Python. In this section, we shall outline the steps -necessary to achieve that. We shall use the build tool that comes bundled +try it for yourself in Python. In this section, we will outline the steps +necessary to achieve that. We will use the build tool that comes bundled with every boost distribution: [*bjam]. -[blurb __note__ [*Building without bjam]\n\n - Besides bjam, there are of course other ways to get your module built. - What's written here should not be taken as "the one and only way". - There are of course other build tools apart from [^bjam].\n\n - Take note however that the preferred build tool for Boost.Python is bjam. - There are so many ways to set up the build incorrectly. Experience shows - that 90% of the "I can't build Boost.Python" problems come from people - who had to use a different tool. +[note [*Building without bjam] + +Besides bjam, there are of course other ways to get your module built. +What's written here should not be taken as "the one and only way". +There are of course other build tools apart from [^bjam]. + +Take note however that the preferred build tool for Boost.Python is bjam. +There are so many ways to set up the build incorrectly. Experience shows +that 90% of the "I can't build Boost.Python" problems come from people +who had to use a different tool. ] -We shall skip over the details. Our objective will be to simply create the -hello world module and run it in Python. For a complete reference to -building Boost.Python, check out: [@../../../building.html building.html]. -After this brief ['bjam] tutorial, we should have built two DLLs: - -* boost_python.dll -* hello.pyd - -if you are on Windows, and - -* libboost_python.so -* hello.so - -if you are on Unix. +We will skip over the details. Our objective will be to simply create +the hello world module and run it in Python. For a complete reference to +building Boost.Python, check out: [@../../../building.html +building.html]. After this brief ['bjam] tutorial, we should have built +the DLLs and run a python program using the extension. The tutorial example can be found in the directory: [^libs/python/example/tutorial]. There, you can find: * hello.cpp -* Jamfile +* hello.py +* Jamroot -The [^hello.cpp] file is our C++ hello world example. The [^Jamfile] is a -minimalist ['bjam] script that builds the DLLs for us. +The [^hello.cpp] file is our C++ hello world example. The [^Jamroot] is +a minimalist ['bjam] script that builds the DLLs for us. Finally, +[^hello.py] is our Python program that uses the extension in +[^hello.cpp]. Before anything else, you should have the bjam executable in your boost directory or somewhere in your path such that [^bjam] can be executed in @@ -122,51 +118,12 @@ platforms. The complete list of Bjam executables can be found [h2 Let's Jam!] __jam__ -Here is our minimalist Jamfile: +[@../../../../example/tutorial/Jamroot Here] is our minimalist Jamroot +file. Simply copy the file and tweak [^use-project boost] to where your +boost root directory is and your OK. -[pre -# This is the top of our own project tree -project-root ; - -import python ; - -extension hello # Declare a Python extension called hello -: hello.cpp # source - # requirements and dependencies for Boost.Python extensions -