From 44e43d3b47295269f67e6f1e17bfacca12af60bb Mon Sep 17 00:00:00 2001 From: Dave Abrahams Date: Thu, 14 Feb 2002 03:39:41 +0000 Subject: [PATCH] Initial checkin of V2 docs [SVN r12797] --- build/Jamfile | 2 +- doc/boost.css | 57 +++++ doc/v2/acknowledgments.html | 31 +++ doc/v2/bibliography.html | 31 +++ doc/v2/call.html | 62 +++++ doc/v2/class.html | 328 +++++++++++++++++++++++++++ doc/v2/class_hpp.py | 20 ++ doc/v2/configuration.html | 90 ++++++++ doc/v2/copy_const_reference.html | 118 ++++++++++ doc/v2/copy_non_const_reference.html | 119 ++++++++++ doc/v2/default_call_policies.html | 144 ++++++++++++ doc/v2/definitions.html | 34 +++ doc/v2/errors.html | 223 ++++++++++++++++++ doc/v2/faq.html | 38 ++++ doc/v2/foo.cpp | 142 ++++++++++++ doc/v2/from_python.html | 156 +++++++++++++ doc/v2/header.html | 181 +++++++++++++++ doc/v2/index.html | 41 ++++ doc/v2/overview.html | 47 ++++ doc/v2/rationale.html | 47 ++++ doc/v2/reference.html | 271 ++++++++++++++++++++++ 21 files changed, 2181 insertions(+), 1 deletion(-) create mode 100644 doc/boost.css create mode 100644 doc/v2/acknowledgments.html create mode 100644 doc/v2/bibliography.html create mode 100644 doc/v2/call.html create mode 100644 doc/v2/class.html create mode 100644 doc/v2/class_hpp.py create mode 100644 doc/v2/configuration.html create mode 100644 doc/v2/copy_const_reference.html create mode 100644 doc/v2/copy_non_const_reference.html create mode 100644 doc/v2/default_call_policies.html create mode 100644 doc/v2/definitions.html create mode 100644 doc/v2/errors.html create mode 100644 doc/v2/faq.html create mode 100644 doc/v2/foo.cpp create mode 100644 doc/v2/from_python.html create mode 100644 doc/v2/header.html create mode 100644 doc/v2/index.html create mode 100644 doc/v2/overview.html create mode 100644 doc/v2/rationale.html create mode 100644 doc/v2/reference.html diff --git a/build/Jamfile b/build/Jamfile index 1ea3665d..7dd6ecfe 100644 --- a/build/Jamfile +++ b/build/Jamfile @@ -9,7 +9,7 @@ # To run all tests with verbose output: jam -sPYTHON_TEST_ARGS=-v test # # Declares the following targets: -# 1. libboost_python, a static link library to be linked with all +# 1. libboost_python.dll/.so, a dynamic library to be linked with all # Boost.Python modules # # 2. pairs of test targets of the form .test and .run diff --git a/doc/boost.css b/doc/boost.css new file mode 100644 index 00000000..c382d4c6 --- /dev/null +++ b/doc/boost.css @@ -0,0 +1,57 @@ +H1 +{ + FONT-SIZE: 200% + COLOR: #00007f +} +H2 +{ + FONT-SIZE: 150%; +} +H3 +{ + FONT-SIZE: 125%; +} +H4 +{ + FONT-SIZE: 108%; +} +BODY +{ + FONT-SIZE: 100%; + BACKGROUND-COLOR: #ffffff +} +PRE +{ + MARGIN-LEFT: 2pc; + BACKGROUND-COLOR: #dfffff +} +CODE +{ + white-space: pre +} +.index +{ + TEXT-ALIGN: left +} +.page-index +{ + TEXT-ALIGN: left +} +.definition +{ + TEXT-ALIGN: left +} +.footnote +{ + FONT-SIZE: 66%; + VERTICAL-ALIGN: super; + TEXT-DECORATION: none +} +.function-semantics +{ + CLEAR: left +} +.metafunction-semantics +{ + CLEAR: left +} diff --git a/doc/v2/acknowledgments.html b/doc/v2/acknowledgments.html new file mode 100644 index 00000000..bd13fa79 --- /dev/null +++ b/doc/v2/acknowledgments.html @@ -0,0 +1,31 @@ + + + + +Boost.Python - Acknowledgments + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Acknowledgments

+
+
+{{text}} +
+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/bibliography.html b/doc/v2/bibliography.html new file mode 100644 index 00000000..e1be0141 --- /dev/null +++ b/doc/v2/bibliography.html @@ -0,0 +1,31 @@ + + + + +Boost.Python - Bibliography + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Bibliography

+
+
+{{bibliographical information}} +
+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/call.html b/doc/v2/call.html new file mode 100644 index 00000000..eb3e706c --- /dev/null +++ b/doc/v2/call.html @@ -0,0 +1,62 @@ + + + + +Boost.Python - <call.hpp> + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Header <call.hpp>

+
+
+

Contents

+
+
Introduction
+ +
Functions
+
+
call
+
+ +
Example(s)
+ +
+
+

Introduction

+

{{Introductory text}}

+ +

Functions

+
+call
+
+
+
Requires: {{text}}
+
Effects: {{text}}
+
Postconditions: {{text}}
+
Returns: {{text}}
+
Throws: {{text}}
+
Complexity: {{text}}
+
Rationale: {{text}}
+
+ +

Example(s)

+ +

{{Example(s)}}

+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/class.html b/doc/v2/class.html new file mode 100644 index 00000000..e6eee244 --- /dev/null +++ b/doc/v2/class.html @@ -0,0 +1,328 @@ + + + + +Boost.Python - <boost/python/class.hpp>, <boost/python/class_fwd.hpp> + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Headers <boost/python/class.hpp>, <boost/python/class_fwd.hpp>

+
+
+

Contents

+
+
Introduction
+ +
Classes
+ +
+ +
Class template class_
+
+
Class class_ synopsis
+
Class class_ constructors
+
Class class_ modifier functions
+
Class class_ observer functions
+
+ +
Class template bases
+
+
Class bases synopsis
+
+ +
Class template args
+
+
Class args synopsis
+
+ +
+ +
Example(s)
+
+
+

Introduction

+ +

<boost/python/class.hpp> defines the interface through + which users expose their C++ classes to Python. It declares the + class_ class template, which is parameterized on the + class type being exposed, and the args and + bases utility class templates in the anonymous + namespace (the latter definitions will probably be moved in a future + release). + +

+ <boost/python/class_fwd.hpp> contains a forward + declaration of the class_ class template. + + +

Classes

+ +

+Class template class_<T, Bases, HolderGenerator>

+ +

Creates a Python class associated with the C++ type passed as its +first parameter. Its template arguments are: +

+ + + + + +
Parameter + Description + Default +
T + The class being exposed to Python +
Bases + An MPL sequence of C++ base classes + An unspecified empty sequence +
HolderGenerator + A type generator for the holder which +maintains the C++ object inside the Python instance. + boost::python::objects::value_holder_generator +
+ + + +

Class template class_ synopsis

+
+namespace boost { namespace python
+{
+
+  template <class T
+            , class Bases = none
+            , class HolderGenerator = objects::value_holder_generator>
+  class class_
+  {
+    class_();
+    class_(char const* name);
+
+    template <class F>
+    class_& def(char const* name, F f);
+
+    template <class Fn, class CallPolicy>
+    class_& def(char const* name, Fn fn, CallPolicy policy);
+    
+    template <class Args>
+    class_& def_init(Args const& = Args());
+
+    class_& def_init();
+
+    ref object() const;
+  };
+}}
+
+ +

Class template class_ constructors

+
+class_()
+
+
+ +
Requires: The platform's + std::type_info::name() implementation produces a string + which corresponds to the type's declaration in C++
+ +
Effects: Constructs a class_ object which + generates a Boost.Python extension class with the same name as + T.
+ +
Rationale: Many platforms can generate reasonable names + for Python classes without user intervention.
+ +
+ +
+class_(char const* name)
+
+
+ +
Requires: Name is a ntbs which conforms to Python's identifier + naming rules.
+ +
Effects: Constructs a class_ object which + generates a Boost.Python extension class named + name.
+ +
Rationale: Gives the user full control over class naming.
+ +
+ +

Class template class_ modifier functions

+ +
+template <class F>
+class_& def(char const* name, F f)
+
+template <class Fn, class CallPolicy>
+class_& def(char const* name, Fn fn, CallPolicy policy)
+
+ +
+
Requires: + + f is a non-null pointer-to-function or + pointer-to-member-function. + + name is a ntbs which conforms to Python's identifier + naming rules. + + If supplied, policy conforms to the CallPolicy concept requirements. +
+ +
Effects: Adds the result of make_function(f) + to the Boost.Python extension class being defined, with the given + name. If the extension class already has an attribute + named name, the usual overloading procedure applies. + +
+ +
Returns: *this
+
+ +
+template <class Args>
+class_& def_init(Args const& argument_types)
+
+class_& def_init()
+
+ +
+ +
Requires: in the first form, argument_types must be an MPL sequence of C++ + argument types (A1, A2,... AN) such that if + a1, a2... aN are objects of type + A1, A2,... AN respectively, the expression + T(a1, a2... aN) is + valid. In the second form, the expression T() must be + valid. +
+ +
Effects: Adds the result of + make_constructor<T,Args,HolderGenerator>() to the + Boost.Python extension class being defined with the name + "__init__". If the 2nd form is used, an unspecified empty + MPL sequence type is + substituted for Args. + If the extension class already has an + "__init__" attribute, the usual overloading procedure applies. + +
Returns: *this
+ +
Rationale: Allows users to easily expose a class' + constructor to Python.
+
+ + +

Class template class_ observer +functions

+
+ref object() const;
+
+
+
Returns: A ref object which holds a + reference to the Boost.Python extension class object created by the + class_ constructor.
+ +
Rationale: Mostly not needed by users, since module::add() uses this to + insert the extension class in the module.
+
+ + +

+Class template args<T1, T2,...TN>

+ +

Essentially an alias for boost::mpl::type_list which +users can use in def_init calls to make their code more +readable. Currently it is in the global unnammed namespace, but that +will probably change. + +

Class template args synopsis

+
+namespace
+{
+  template <T1 = unspecified,...TN = unspecified>
+  struct args : ::boost::mpl::type_list<T1,...TN>::type
+  {};
+}
+
+ +

+Class template bases<T1, T2,...TN>

+ +

Essentially an alias for boost::mpl::type_list which +users can use in class_<...> +instantiations to make their code more readable. Currently it is in +the global unnammed namespace, but that will probably change. + +

Class template bases synopsis

+
+namespace
+{
+  template <T1 = unspecified,...TN = unspecified>
+  struct bases : ::boost::mpl::type_list<T1,...TN>::type
+  {};
+}
+
+ +

Example(s)

+ +

Given a C++ class declaration: + +

+class Foo : public Bar, public Baz
+{
+ public:
+   Foo(int, char const*);
+   Foo(double);
+
+   std::string const& name() { return m_name; }
+   void name(char const*);
+ private:
+   ...
+};
+
+ +A corresponding Boost.Python extension class can be created with: + +
+using namespace boost::python;
+ref foo =
+class_<Foo,bases<Bar,Baz> >()
+   .def_init(args<int,char const*>())
+   .def_init(args<double>())
+   .def("get_name", &Foo::get_name, return_internal_reference<>())
+   .def("set_name", &Foo::set_name)
+   .object();
+
+ +

+ +

Revised + + 05 November, 2001 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/class_hpp.py b/doc/v2/class_hpp.py new file mode 100644 index 00000000..9af2cb5c --- /dev/null +++ b/doc/v2/class_hpp.py @@ -0,0 +1,20 @@ +introduction = ''' +''' + +class boost(namespace): pass + +class python(boost): + + class class_(class_template): + T = type() + T.requires = 'a class type' + + Bases = concepts.mpl_sequence('class type') + HolderGenerator = concepts.HolderGenerator() + template_args = (T, Bases, HolderGenerator) + + class def_1(function_template): + name = "def" + args = (('char const*', 'name'), ('F', 'f')) + +class_template diff --git a/doc/v2/configuration.html b/doc/v2/configuration.html new file mode 100644 index 00000000..18b065d1 --- /dev/null +++ b/doc/v2/configuration.html @@ -0,0 +1,90 @@ + + + + +Boost.Python - Configuration + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Configuration

+
+
+
+
Introduction
+
Application Defined Macros
+
Public Library Defined Macros
+
Library Defined Implementation Macros
+
+

Introduction

+

Boost.Python uses several configuration macros in <boost/config.hpp>, + as well as configuration macros meant to be supplied by the application. These + macros are documented here.

+

Application Defined Macros

+

These are the macros that may be defined by an application using Boost.Python.

+ + + + + + + + + + + + + +
MacroMeaning
{{macro}}{{meaning}}
{{macro}}{{meaning}}
+

Public Library Defined Macros

+

These macros are defined by Boost.Python but are expected to be used by application + code.

+ + + + + + + + + + + + + +
MacroMeaning
{{macro}}{{meaning}}
{{macro}}{{meaning}}
+

Library Defined Implementation Macros

+

These macros are defined by Boost.Python and are implementation details of interest + only to implementers.

+ + + + + + + + + + + + + +
MacroMeaning
{{macro}}{{meaning}}
{{macro}}{{meaning}}
+
+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/copy_const_reference.html b/doc/v2/copy_const_reference.html new file mode 100644 index 00000000..1ce94dbb --- /dev/null +++ b/doc/v2/copy_const_reference.html @@ -0,0 +1,118 @@ + + + + +Boost.Python - <boost/python/copy_const_reference.hpp> + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Header <boost/python/copy_const_reference.hpp>

+
+
+

Contents

+
+
Classes
+
+
Class copy_const_reference
+
+
Class copy_const_reference synopsis
+
Class copy_const_reference metafunctions
+
+
+ +
Example
+
+
+ +

Classes

+ +

Class copy_const_reference

+

+copy_const_reference is a model of ResultConverterGenerator +which can be used to wrap C++ functions returning a reference-to-const +type such that the referenced value is copied into a new Python object. +

+ +

Class copy_const_reference synopsis

+
+namespace boost { namespace python
+{
+    struct copy_const_reference
+    {
+        template <class T> struct apply;
+    };
+}}
+
+

Class copy_const_reference metafunctions

+
+template <class T> struct apply
+
+
+
Requires: T is U const& for some U.
+
Returns: typedef to_python_value<T> type;
+
+ +

Example

+ +

In C++: + +

+#include <boost/python/module.hpp>
+#include <boost/python/class.hpp>
+#include <boost/python/copy_const_reference.hpp>
+#include <boost/python/return_value_policy.hpp>
+
+// classes to wrap
+struct Bar { int x; }
+
+struct Foo {
+   Foo(int x) : { b.x = x; }
+   Bar const& get_bar() const { return b; }
+ private:
+   Bar b;
+};
+
+// Wrapper code
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(my_module)
+{
+   module m("my_module")
+      .add(
+         class_<Bar>()
+         )
+      .add(
+         class_<Foo>()
+            .def_init(args<int>())
+            .def("get_bar", &Foo::get_bar
+                , return_value_policy<copy_const_reference>())
+         );
+}
+
+ +In Python: + +
+>>> from my_module import *
+>>> f = Foo(3)         # create a Foo object
+>>> b = f.get_bar()    # make a copy of the internal Bar object
+
+ +

Revised + + 05 November, 2001 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/copy_non_const_reference.html b/doc/v2/copy_non_const_reference.html new file mode 100644 index 00000000..c1ed50a3 --- /dev/null +++ b/doc/v2/copy_non_const_reference.html @@ -0,0 +1,119 @@ + + + + +Boost.Python - <boost/python/copy_non_const_reference.hpp> + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Header <boost/python/copy_non_const_reference.hpp>

+
+
+

Contents

+
+
Classes
+
+
Class copy_non_const_reference
+
+
Class copy_non_const_reference synopsis
+
Class copy_non_const_reference metafunctions
+
+
+ +
Example
+
+
+ +

Classes

+ +

Class copy_non_const_reference

+

+copy_non_const_reference is a model of ResultConverterGenerator +which can be used to wrap C++ functions returning a reference-to-non-const +type such that the referenced value is copied into a new Python object. +

+ +

Class copy_non_const_reference synopsis

+
+namespace boost { namespace python
+{
+    struct copy_non_const_reference
+    {
+        template <class T> struct apply;
+    };
+}}
+
+ +

Class copy_non_const_reference metafunctions

+
+template <class T> struct apply
+
+
+
Requires: T is U& for some non-const U.
+
Returns: typedef to_python_value<T> type;
+
+ +

Example

+ +

C++ code: + +

+#include <boost/python/module.hpp>
+#include <boost/python/class.hpp>
+#include <boost/python/copy_non_const_reference.hpp>
+#include <boost/python/return_value_policy.hpp>
+
+// classes to wrap
+struct Bar { int x; }
+
+struct Foo {
+   Foo(int x) : { b.x = x; }
+   Bar& get_bar() { return b; }
+ private:
+   Bar b;
+};
+
+// Wrapper code
+using namespace boost::python;
+BOOST_PYTHON_MODULE_INIT(my_module)
+{
+   module m("my_module")
+      .add(
+         class_<Bar>()
+         )
+      .add(
+         class_<Foo>()
+            .def_init(args<int>())
+            .def("get_bar", &Foo::get_bar
+                , return_value_policy<copy_non_const_reference>())
+         );
+}
+
+ +Python Code: + +
+>>> from my_module import *
+>>> f = Foo(3)         # create a Foo object
+>>> b = f.get_bar()    # make a copy of the internal Bar object
+
+ +

Revised + + 05 November, 2001 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/default_call_policies.html b/doc/v2/default_call_policies.html new file mode 100644 index 00000000..3e60fcc8 --- /dev/null +++ b/doc/v2/default_call_policies.html @@ -0,0 +1,144 @@ + + + + +Boost.Python - <boost/python/default_call_policies.hpp> + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Header <boost/python/default_call_policies.hpp>

+
+
+

Contents

+
+
Classes
+
+ +
Class default_call_policies
+
+
Class default_call_policies synopsis
+
Class default_call_policies static functions
+
+ +
Class default_result_converter
+
+
Class default_result_converter synopsis
+
Class default_result_converter metafunctions
+
+ +
+ +
Example
+
+
+ +

Classes

+ +

Class default_call_policies

+

+default_call_policies is a model of CallPolicies with no precall +or postcall behavior and a result_converter +which handles by-value returns. Wrapped C++ functions and member +functions use default_call_policies unless otherwise +specified. You may find it convenient to derive new models of CallPolicies from +default_call_policies. +

+ +

Class default_call_policies synopsis

+
+namespace boost { namespace python
+{
+    struct default_call_policies
+    {
+        static bool precall(PyObject*);
+        static PyObject* postcall(PyObject*, PyObject* result);
+        typedef default_result_converter result_converter;
+    };
+}}
+
+ +

Class default_call_policies static functions

+
+bool precall(PyObject*);
+
+
+
Returns: true
+
Throws: nothing
+
+ +
+PyObject* postcall(PyObject*, PyObject* result);
+
+
+
Returns: result
+
Throws: nothing
+
+ +

Class default_result_converter

+

+default_result_converter is a model of ResultConverterGenerator +which can be used to wrap C++ functions returning non-pointer types, +char const*, and PyObject*, +by-value. +

+ +

Class default_result_converter synopsis

+
+namespace boost { namespace python
+{
+    struct default_result_converter
+    {
+        template <class T> struct apply;
+    };
+}}
+
+ +

Class default_result_converter metafunctions

+
+template <class T> struct apply
+
+
+ +
Requires: T is not a reference type. If + T is a pointer type, T is const + char* or PyObject*.
+ +
Returns: typedef to_python_value<T const&> type;
+
+ +

Example

+ +

This example comes from the Boost.Python implementation itself. Because the return_value_policy +class template does not implement precall or +postcall behavior, its default base class is default_call_policies: + +

+template <class Handler, class Base = default_call_policies>
+struct return_value_policy : Base
+{
+   typedef Handler result_converter;
+};
+
+ +

Revised + + 05 November, 2001 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/definitions.html b/doc/v2/definitions.html new file mode 100644 index 00000000..dd917434 --- /dev/null +++ b/doc/v2/definitions.html @@ -0,0 +1,34 @@ + + + + +Boost.Python - Definitions + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Definitions

+
+
+
+
{{term}}: {{definition}}
+
{{term}}: {{definition}}
+
+
+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/errors.html b/doc/v2/errors.html new file mode 100644 index 00000000..b46de25c --- /dev/null +++ b/doc/v2/errors.html @@ -0,0 +1,223 @@ + + + + +Boost.Python - <{{header}}> + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Header <boost/python/errors.hpp>

+
+
+

Contents

+
+
Introduction
+ +
Classes
+
+ +
Class error_already_set
+
+
Class error_already_set synopsis
+
+ +
+ +
Functions
+
+ +
handle_exception
+
expect_non_null
+ +
+ +
Examples
+
+
+ +

Introduction

+

<boost/python/errors.hpp> provides types and +functions for managing and translating between Python and C++ +exceptions. This is relatively low-level functionality that is mostly +used internally by Boost.Python. Users should seldom need it. + +

Classes

+ +

Class error_already_set

+

+error_already_set is an exception type which can be +thrown to indicate that a Python error has occurred. If thrown, the +precondition is that PyErr_Occurred() +returns a value convertible to true. +

+ +

Class error_already_set synopsis

+
+namespace boost { namespace python
+{
+    class error_already_set {};
+}}
+
+ + +

Functions

+
template <class T> bool handle_exception(T f) throw();
+
+void handle_exception() throw();
+
+
+
Requires: The first form requires that the expression + function0<void>(f) + is valid. The second form requires that a C++ exception is currently + being handled (see section 15.1 in the C++ standard). +
+ +
Effects: The first form calls f() inside a + try block whose catch clauses set an + appropriate Python exception for the C++ exception caught, returning + true if an exception was caught, false + otherwise. The second form passes a function which rethrows the + exception currently being handled to the first form.
+ +
Postconditions: No exception is being handled
+ +
Throws: nothing
+ +
Rationale: At inter-language boundaries it is important + to ensure that no C++ exceptions escape, since the calling language + usually doesn't have the equipment neccessary to properly unwind the + stack. Use handle_exception to manage exception + translation whenever your C++ code is called directly from the + Python API. This is done for you automatically by the usual function + wrapping facilities: make_function(), make_constructor(), + module::def and class_::def). The second form can be + more convenient to use + (see the example below), but various + compilers have problems when exceptions are rethrown from within an + enclosing try block.
+
+ +
+PyObject* expect_non_null(PyObject* x);
+
+template <class T> T* expect_non_null(T* x);
+
+
+
Returns: x
+
Throws: error_already_set() iff x == 0.
+
Rationale: Simplifies error-handling when calling many + functions in the Python/C + API, which return 0 on error.
+
+ +

Examples

+

+

+#include <string>
+#include <boost/python/errors.hpp>
+#include <boost/python/reference.hpp>
+
+// Returns a std::string which has the same value as obj's "__name__"
+// attribute.
+std::string get_name(boost::python::ref obj)
+{
+   // throws if there's no __name__ attribute
+   PyObject* p = boost::python::expect_non_null(
+      PyObject_GetAttrString(obj.get(), "__name__"));
+
+   // throws if it's not a Python string
+   std::string result(
+      boost::python::expect_non_null(
+         PyString_AsString(p)));
+
+   Py_XDECREF(p); // Done with p
+   
+   return result;
+}
+
+//
+// Demonstrate form 1 of handle_exception
+//
+
+// Place a Python Int object whose value is 1 if a and b have
+// identical "__name__" attributes, 0 otherwise.
+void same_name_impl(PyObject*& result, PyObject* a, PyObject* b)
+{
+   result = PyInt_FromLong(
+      get_name(boost::python::ref(a1)) == get_name(boost::python::ref(a2)));
+}
+
+// This is an example Python 'C' API interface function
+extern "C" PyObject*
+same_name(PyObject* args, PyObject* keywords)
+{
+   PyObject* a1;
+   PyObject* a2;
+   PyObject* result = 0;
+
+   if (!PyArg_ParseTuple(args, const_cast<char*>("OO"), &a1, &a2))
+      return 0;
+   
+   // Use boost::bind to make an object compatible with
+   // boost::Function0<void>
+   if (boost::python::handle_exception(
+         boost::bind<void>(same_name_impl, boost::ref(result), a1, a2)))
+   {
+      // an exception was thrown; the Python error was set by
+      // handle_exception()
+      return 0;
+   }
+
+   return result;
+}
+
+//
+// Demonstrate form 2 of handle_exception. Not well-supported by all
+// compilers.
+//
+extern "C" PyObject*
+same_name2(PyObject* args, PyObject* keywords)
+{
+   PyObject* a1;
+   PyObject* a2;
+   PyObject* result = 0;
+
+   if (!PyArg_ParseTuple(args, const_cast<char*>("OO"), &a1, &a2))
+      return 0;
+   try {
+      return PyInt_FromLong(
+         get_name(boost::python::ref(a1)) == get_name(boost::python::ref(a2)));
+   }
+   catch(...)
+   {
+      // If an exception was thrown, translate it to Python
+      boost::python::handle_exception();
+      return 0;
+   }
+}
+
+

+

Revised + + 05 November, 2001 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/faq.html b/doc/v2/faq.html new file mode 100644 index 00000000..dae93fa5 --- /dev/null +++ b/doc/v2/faq.html @@ -0,0 +1,38 @@ + + + + +Boost.Python - FAQ + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Frequently Asked Questions (FAQs)

+
+
+
+
{{question}}
+
{{question}}
+
+

{{question}}

+

{{answer}}

+

{{question}}

+

{{answer}}

+
+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/foo.cpp b/doc/v2/foo.cpp new file mode 100644 index 00000000..e92c2d72 --- /dev/null +++ b/doc/v2/foo.cpp @@ -0,0 +1,142 @@ +// Copyright David Abrahams 2002. Permission to copy, use, +// modify, sell and distribute this software is granted provided this +// copyright notice appears in all copies. This software is provided +// "as is" without express or implied warranty, and with no claim as +// to its suitability for any purpose. + + +#include +#include +#include +#include + +class Bar { int x; } + +class Foo +{ + public: + Foo(int x) : b(x) {} + Bar const& get_bar() const { return b; } + private: + Bar b; +}; + +using namespace boost::python; +BOOST_PYTHON_MODULE_INIT(my_module) +{ + module m("my_module") + .add( + class_() + ) + .add( + class_() + .def_init(args()) + .def("get_bar", &Foo::get_bar + , return_value_policy()) + ) +} + +using namespace boost::python; +ref foo = +class_ >() + .def_init(args()) + .def_init(args()) + .def("get_name", &Foo::get_name, return_internal_reference<>()) + .def("set_name", &Foo::set_name) + .object(); + + +
+#include <string>
+#include <boost/python/errors.hpp>
+#include <boost/python/reference.hpp>
+
+// Returns a std::string which has the same value as obj's "__name__"
+// attribute.
+std::string get_name(boost::python::ref obj)
+{
+    // throws if there's no __name__ attribute
+    PyObject* p = boost::python::expect_non_null(
+        PyObject_GetAttrString(obj.get(), "__name__"));
+
+    // throws if it's not a Python string
+    std::string result(
+        boost::python::expect_non_null(
+            PyString_AsString(p)));
+
+    Py_XDECREF(p); // Done with p
+    
+    return result;
+}
+
+//
+// Demonstrate form 1 of handle_exception
+//
+
+// Place a Python Int object whose value is 1 if a and b have
+// identical "__name__" attributes, 0 otherwise.
+void same_name_impl(PyObject*& result, PyObject* a, PyObject* b)
+{
+    result = PyInt_FromLong(
+        get_name(boost::python::ref(a1)) == get_name(boost::python::ref(a2)));
+}
+
+// This is an example Python 'C' API interface function
+extern "C" PyObject*
+same_name(PyObject* args, PyObject* keywords)
+{
+    PyObject* a1;
+    PyObject* a2;
+    PyObject* result = 0;
+
+    if (!PyArg_ParseTuple(args, const_cast<char*>("OO"), &a1, &a2))
+        return 0;
+    
+    // Use boost::bind to make an object compatible with
+    // boost::Function0<void>
+    if (boost::python::handle_exception(
+            boost::bind<void>(same_name_impl, boost::ref(result), a1, a2)))
+    {
+        // an exception was thrown; the Python error was set by
+        // handle_exception()
+        return 0;
+    }
+
+    return result;
+}
+
+//
+// Demonstrate form 2 of handle_exception. Not well-supported by all
+// compilers.
+//
+extern "C" PyObject*
+same_name2(PyObject* args, PyObject* keywords)
+{
+    PyObject* a1;
+    PyObject* a2;
+    PyObject* result = 0;
+
+    if (!PyArg_ParseTuple(args, const_cast<char*>("OO"), &a1, &a2))
+        return 0;
+    try {
+        return PyInt_FromLong(
+            get_name(boost::python::ref(a1)) == get_name(boost::python::ref(a2)));
+    }
+    catch(...)
+    {
+        // If an exception was thrown, translate it to Python
+        boost::python::handle_exception();
+        return 0;
+    }
+}
+
+
+ + +template +struct from_python +{ + from_python(PyObject*); + bool convertible() const; + X operator()(PyObject*) const; +}; diff --git a/doc/v2/from_python.html b/doc/v2/from_python.html new file mode 100644 index 00000000..94ae7019 --- /dev/null +++ b/doc/v2/from_python.html @@ -0,0 +1,156 @@ + + + + +Boost.Python - <boost/python/from_python.hpp> + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Header <boost/python/from_python.hpp>

+
+
+

Contents

+
+
Introduction
+ +
Classes
+
+ +
Class Templatefrom_python
+
+
Class Template from_python synopsis
+
Class Template from_python constructor
+
Class Template from_python observer functions
+
+
+
Example
+
+
+

Introduction

+

+ +<boost/python/from_python.hpp> introduces a class +template from_python<T> for extracting a C++ object +of type T from a Python object. + +

+ + +

Classes

+

Class Template from_python<class T>

+ +

+from_python<T> is the type used internally by +Boost.Python to extract C++ function arguments from a Python argument +tuple when calling a wrapped function. It can also be used directly to +make similar conversions in other contexts. +

+ +

Class Template from_python synopsis

+
+namespace boost { namespace python
+{
+   template <class T>
+   struct from_python : private boost::noncopyable // Exposition only.
+       // from_python<T> meets the NonCopyable requirements
+   {
+      from_python(PyObject*);
+      bool convertible() const;
+      convertible-to-T operator()(PyObject*) const;
+   };
+}
+
+ +

Class Template from_python constructor

+
+from_python(PyObject* p);
+
+
+
Requires: p != 0
+ +
Effects: Constructs a from_python object + suitable for extracting a C++ object of type T from + p.
+
+ +

Class Template from_python observer functions

+ +
+bool convertible() const;
+
+
+ +
Returns: false if the conversion cannot succeed. This indicates that either: +
    +
  1. No from_python_converter was registered for +T, or + +
  2. any such converter rejected the constructor argument +p by returning 0 from its +convertible() function +
+ +Note that conversion may still fail in operator() due to an exception. + +
+ +
Throws: nothing
+ +
Rationale: Because from_python<> is used in + overload resolution, and throwing an exception can be slow, it is + useful to be able to rule out a broad class of unsuccessful + conversions without throwing an exception.
+
+ +
+convertible-to-T operator()(PyObject* p) const;
+
+
+ +
Requires: *p refers to the same object which + was passed to the constructor, and convertible() + returns true.
+ +
Effects: performs the conversion
+
Returns: an object convertible to T.
+
+ +

Example

+ +

+

+#include <string>
+#include <boost/python/from_python.hpp>
+
+// If a std::string can be extracted from p, return its
+// length. Otherwise, return 0.
+std::size_t length_if_string(PyObject* p)
+{
+   from_python<std::string> converter(p);
+   if (!converter.convertible())
+      return 0;
+   else
+      return converter().size();
+}
+
+

+ +

Revised + + 05 November, 2001 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/header.html b/doc/v2/header.html new file mode 100644 index 00000000..c0fa972f --- /dev/null +++ b/doc/v2/header.html @@ -0,0 +1,181 @@ + + + + +Boost.Python - <{{header}}> + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Header <{{header}}>

+
+
+

Contents

+
+
Introduction
+
Macros
+
+
{{macro name}}
+
+
Values
+
+
{{value name}}
+
+
Types
+
+
{{type name}}
+
+
Classes
+
+
Class {{class name}}
+
+
Class {{class name}} synopsis
+
Class {{class name}} constructors and destructor
+
Class {{class name}} comparison functions
+
Class {{class name}} modifier functions
+
Class {{class name}} observer functions
+
Class {{class name}} static functions
+
+
+
Functions
+
+
{{function name}}
+
+
Objects
+
+
{{object name}}
+
+
Example(s)
+
+
+

Introduction

+

{{Introductory text}}

+

Macros

+

{{Macro specifications}}

+

Values

+

{{Value specifications}}

+

Types

+

{{Type specifications}}

+

Classes

+

Class {{name}}

+

{{class overview text}}

+

Class {{name}} synopsis

+
+namespace boost
+{
+    class {{name}}
+	{
+	};
+};
+
+

Class {{name}} constructors and destructor

+
+{{constructor}}
+
+
+
Requires: {{text}}
+
Effects: {{text}}
+
Postconditions: {{text}}
+
Returns: {{text}}
+
Throws: {{text}}
+
Complexity: {{text}}
+
Rationale: {{text}}
+
+
+{{destructor}}
+
+
+
Requires: {{text}}
+
Effects: {{text}}
+
Postconditions: {{text}}
+
Returns: {{text}}
+
Throws: {{text}}
+
Complexity: {{text}}
+
Rationale: {{text}}
+
+

Class {{name}} comparison functions

+
+{{function}}
+
+
+
Requires: {{text}}
+
Effects: {{text}}
+
Postconditions: {{text}}
+
Returns: {{text}}
+
Throws: {{text}}
+
Complexity: {{text}}
+
Rationale: {{text}}
+
+

Class {{name}} modifier functions

+
+{{function}}
+
+
+
Requires: {{text}}
+
Effects: {{text}}
+
Postconditions: {{text}}
+
Returns: {{text}}
+
Throws: {{text}}
+
Complexity: {{text}}
+
Rationale: {{text}}
+
+

Class {{name}} observer functions

+
+{{function}}
+
+
+
Requires: {{text}}
+
Effects: {{text}}
+
Postconditions: {{text}}
+
Returns: {{text}}
+
Throws: {{text}}
+
Complexity: {{text}}
+
Rationale: {{text}}
+
+

Class {{name}} static functions

+
+{{function}}
+
+
+
Requires: {{text}}
+
Effects: {{text}}
+
Postconditions: {{text}}
+
Returns: {{text}}
+
Throws: {{text}}
+
Complexity: {{text}}
+
Rationale: {{text}}
+
+

Functions

+
+{{function}}
+
+
+
Requires: {{text}}
+
Effects: {{text}}
+
Postconditions: {{text}}
+
Returns: {{text}}
+
Throws: {{text}}
+
Complexity: {{text}}
+
Rationale: {{text}}
+
+

Objects

+

{{Object specifications}}

+

Example(s)

+

{{Example(s)}}

+

Revised + + 05 November, 2001 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/index.html b/doc/v2/index.html new file mode 100644 index 00000000..dea1db6e --- /dev/null +++ b/doc/v2/index.html @@ -0,0 +1,41 @@ + + + + +Boost.Python + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Index

+
+
+

Contents

+
+
Overview
+
Reference
+
Configuration Information
+
Rationale
+
Definitions
+
Frequently Asked Questions (FAQs)
+
Bibliography
+
Acknowledgments
+
+
+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/overview.html b/doc/v2/overview.html new file mode 100644 index 00000000..57d0e36e --- /dev/null +++ b/doc/v2/overview.html @@ -0,0 +1,47 @@ + + + + +Boost.Python - Overview + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Overview

+
+
+
+
Introduction
+
First topic
+
Second topic
+
Footnotes
+
+

Introduction

+

{{text}}

+

First Topic

+

{{text}}

+

Second Topic

+

{{text}}

+

Footnotes

+
+
(1) {{text}}
+
(2) {{text}}
+
+
+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/rationale.html b/doc/v2/rationale.html new file mode 100644 index 00000000..da7e9217 --- /dev/null +++ b/doc/v2/rationale.html @@ -0,0 +1,47 @@ + + + + +Boost.Python - Rationale + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Rationale

+
+
+
+
Introduction
+
First topic
+
Second topic
+
Footnotes
+
+

Introduction

+

{{text}}

+

First Topic

+

{{text}}

+

Second Topic

+

{{text}}

+

Footnotes

+
+
(1) {{text}}
+
(2) {{text}}
+
+
+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ + diff --git a/doc/v2/reference.html b/doc/v2/reference.html new file mode 100644 index 00000000..0aa546e5 --- /dev/null +++ b/doc/v2/reference.html @@ -0,0 +1,271 @@ + + + + +Boost.Python - Reference + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+

Reference

+
+
+

Contents

+
+
High Level Components
+
Framework Elements
+
Utilities
+
Index By Name
+
+ +

High Level Components

+
+ +

General Purpose

+
+ +
class.hpp/class_fwd.hpp
+
+
Classes
+
+
class_
+
bases
+
args
+
+ + +
+ +
errors.hpp
+
+ +
Classes
+
+
error_already_set
+
+
Functions
+
+
handle_exception
+
expect_non_null
+
+
+ +
make_function.hpp
+
+
Functions
+
+
make_function
+
make_constructor
+
+
+ +
module.hpp
+
+
Classes
+
+
module
+
+ +
+ +
objects.hpp
+
+
Classes
+
+
not yet documented
+
+ +
+ +
reference.hpp
+
+
Classes
+
+
reference
+
+ +
Types
+
+
ref
+
+ +
+ + +
+ +

To/From Python Type Conversion

+
+ +
from_python.hpp
+
+
Classes
+
+
from_python
+
+
+ +
to_python_converter.hpp
+
+
Classes
+
+
to_python_converter
+
+ +
+ +
to_python_indirect.hpp
+
+
Classes
+
+
to_python_indirect
+
+ +
+ +
to_python_value.hpp
+
+
Classes
+
+
to_python_value
+
+ +
+ +
type_from_python.hpp
+
+
Classes
+
+
type_from_python
+
+ +
+ + +
value_from_python.hpp
+
+
Classes
+
+
value_from_python
+
+ +
+ +
+ + +

Models of CallPolicies

+
+ +
default_call_policies.hpp
+
+
Classes
+
+
default_call_policies
+
default_result_converter
+
+ +
+ +
return_internal_reference.hpp
+
+
Classes
+
+
return_internal_reference
+
+ +
+ +
return_value_policy.hpp
+
+
Classes
+
+
return_value_policy
+
+ +
+ +
with_custodian_and_ward.hpp
+
+
Classes
+
+
with_custodian_and_ward
+
with_custodian_and_ward_postcall
+
+ +
+ +
+ +

Models of ReturnHandlerGenerator

+
+ +
copy_const_reference.hpp
+
+
Classes
+
+
copy_const_reference
+
+ +
+ +
copy_non_const_reference.hpp
+
+
Classes
+
+
copy_non_const_reference
+
+ +
+ + +
manage_new_object.hpp
+
+
Classes
+
+
manage_new_object
+
+ +
+ +
reference_existing_object.hpp
+
+
Classes
+
+
reference_existing_object
+
+ +
+ +
reference_from_python.hpp
+
+
Classes
+
+
reference_from_python
+
get_member
+
+ +
+ +
+ +
+ +
+

Revised + + 05 November, 2002 + +

+

© Copyright Dave Abrahams + 2002. All Rights Reserved.

+ +