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

C++ Boost

+ 		+

Boost.Python

+ +

ObjectWrapper and TypeWrapper Concepts

+
+
+ +
+
Introduction
+ +
Concept Requirements
+ +
+
+
ObjectWrapper Concept
+ +
TypeWrapper Concept
+
+
+ +
Caveat
+
+ +

Introduction

+ +

This page defines two concepts used to describe classes which manage a + Python objects, and which are intended to support usage with a + Python-like syntax.

+ +

Concept Requirements

+ +

ObjectWrapper Concept

+ Models of the ObjectWrapper concept have object as a publicly-accessible base class, + and are used to supply special construction behavior and/or additional + convenient functionality through (often templated) member functions. + Except when the return type R is itself an TypeWrapper, a member function invocation of + the form +
+x.some_function(a1, a2,...an)
+
+ always has semantics equivalent to: +
+extract<R>(x.attr("some_function")(object(a1), object(a2),...object(an)))()
+
+ When the R is an TypeWrapper, the result type may be + constructed by taking direct posession of: +
+x.attr("some_function")(object(a1), object(a2),...object(an)).ptr()
+
+ [see caveat below] + +

TypeWrapper Concept

+ TypeWrapper is a refinement of ObjectWrapper which is associated with a + particular Python type X. For a given TypeWrapper + T, a valid constructor expression +
+T(a1, a2,...an)
+
+ builds a new T object managing the result of invoking + X with arguments corresponding to +
+object(a1), object(a2),...object(an)
+
+ +When used as arguments to wrapped C++ functions, or as the template +parameter to extract<>, only +instances of the associated Python type will be considered a match. + +

Caveat

+ The upshot of the special member function invocation rules when the + return type is a TypeWrapper is that it is possible for the returned + object to manage a Python object of an inappropriate type. This is not + usually a serious problem; the worst-case result is that errors will be + detected at runtime a little later than they might otherwise be. For an + example of how this can occur, note that the dict member function items + returns an object of type list. Now suppose the user defines this + dict subclass in Python: +
+>>> class mydict(dict):
+...     def items(self):
+...         return tuple(dict.items(self)) # return a tuple
+
+ Since an instance of mydict is also an instance of + dict, when used as an argument to a wrapped C++ function, + boost::python::dict can + accept objects of Python type mydict. Invoking + items() on this object can result in an instance of boost::python::list which actually + holds a Python tuple. Subsequent attempts to use list methods (e.g. + append, or any other mutating operation) on this object will + raise the same exception that would occur if you tried to do it from + Python. +
+ +

Revised + + 30 Sept, 2002 +

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

+ +

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.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/args.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
keyword-expressions
+ +
Functions
+ +
+
+
args(...)
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

Supplies a family of overloaded functions for specifying argument + keywords for wrapped C++ functions.

+ +

keyword-expressions

+ +

A keyword-expression results in an object which holds a + sequence of ntbses, and whose type + encodes the number of keywords specified.

+ +

Functions

+ +

args(...)

+
+unspecified1 args(char const*);
+unspecified2 args(char const*, char const*);
+   .
+   .
+   .
+unspecifiedN args(char const*, char const*, ... char const*);
+
+ +
+
Requires: Every argument must be a ntbs.
+ +
Returns: an object representing a keyword-expression encapsulating the + arguments passed.
+
+ +

Example

+
+#include <boost/python/def.hpp>
+using namespace boost::python;
+
+int f(int x, int y, int z);
+
+BOOST_PYTHON_MODULE(xxx)
+{
+   def("f", f, args("x", "y", "z"));
+}
+
+ +

Revised 05 November, 2001

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/def.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Functions
+ +
+
+
def
+
+
+ +
Example
+
+
+ +

Introduction

+ +

def() is the function which can + be used to expose C++ functions and callable objects as Python functions + in the current scope.

+ +

Functions

+
+template <class F>
+void def(char const* name, F f);
+
+template <class Fn, class A1>
+void def(char const* name, Fn fn, A1 const&);
+
+template <class Fn, class A1, class A2>
+void def(char const* name, Fn fn, A1 const&, A2 const&);
+
+template <class Fn, class A1, class A2, class A3>
+void def(char const* name, Fn fn, A1 const&, A2 const&, A3 const&);
+
+ +
+
Requires: name is an ntbs which conforms to Python's identifier + naming rules.
+ +
+ +
+
+ +

Example

+
+#include <boost/python/def.hpp>
+#include <boost/python/module.hpp>
+#include <boost/python/args.hpp>
+
+char const* foo(int x, int y) { return "foo"; }
+
+BOOST_PYTHON_MODULE(def_test)
+{
+    def("foo", foo, args("x", "y"), "foo's docstring");
+}
+
+ +

+ + 03 October, 2002 + +

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/dict.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class dict
+ +
+
+
Class dict + synopsis
+
+
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

Exposes a TypeWrapper for the Python + dict + type.

+ +

Classes

+ +

Class dict

+ +

Exposes the mapping + protocol of Python's built-in dict type. The semantics + of the constructors and member functions defined below can be fully + understood by reading the TypeWrapper concept + definition. Since dict is publicly derived from object, the public object + interface applies to dict instances as well.

+ +

Class dict + synopsis

+
+namespace boost { namespace python
+{
+   class dict : public object
+   {
+      dict();
+
+      template< class T >
+      dict(T const & data);
+
+      // modifiers
+      void clear();
+      dict copy();
+
+      template <class T1, class T2>
+      tuple popitem();
+
+      template <class T>
+      object setdefault(T const &k);
+
+      template <class T1, class T2>
+      object setdefault(T1 const & k, T2 const & d);
+
+      void update(object_cref E);
+ 
+      template< class T >
+      void update(T const & E);
+
+      // observers
+      list values() const;
+    
+      object get(object_cref k) const;
+
+      template<class T>
+      object get(T const & k) const;
+
+      object get(object_cref k, object_cref d) const;
+      object get(T1 const & k, T2 const & d) const;
+
+      bool has_key(object_cref k) const;
+
+      template< class T >
+      bool has_key(T const & k) const;
+
+      list items() const;
+      object iteritems() const;
+      object iterkeys() const;
+      object itervalues() const;
+      list keys() const;
+  };
+}}
+
+ +

Example

+
+using namespace boost::python;
+dict swap_object_dict(object target, dict d)
+{
+    dict result = extract<dict>(target.attr("__dict__"));
+    target.attr("__dict__") = d;
+    return result;
+}
+
+ +

Revised 30 September, 2002

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/enum.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class template + enum_
+ +
+
+
Class template enum_ + synopsis
+ +
Class template enum_ + constructors
+ +
Class template enum_ + modifier functions
+
+
+ +
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

<boost/python/enum.hpp> defines the + interface through which users expose their C++ enumeration types + to Python. It declares the + enum_ class template, which is parameterized on the + enumeration type being exposed.

+ + +

Classes

+ +

Class template + enum_<T>

+ +

Creates a Python class derived from Python's int + type which is associated with the C++ type passed as its first + parameter. + +

Class template enum_ + synopsis

+
+namespace boost { namespace python
+{
+  template <class T>
+  class enum_ : public object
+  {
+    enum_(char const* name);
+    inline enum_<T>& value(char const* name, T);
+  };
+}}
+
+ +

Class template enum_ + constructors

+
+enum_(char const* name);
+
+ +
+
Requires: name is an ntbs which conforms to Python's identifier + naming rules. + +
Effects: Constructs an enum_ object + holding a Python extension type derived from int + which is named name. The + named attribute of the current scope is bound to the new + extension type.
+
+ +

Class template + enum_ modifier functions

+
+inline enum_<T>& value(char const* name, T x);
+
+ +
+
Requires: name is an ntbs which conforms to Python's identifier + naming rules. + +
Effects: adds an instance of the wrapped enumeration + type with value x to the type's dictionary as the + named attribute
. + +
Returns: *this
+ +
+ +

Example(s)

+ +

C++ module definition +

+#include <boost/python/enum.hpp>
+#include <boost/python/def.hpp>
+#include <boost/python/module.hpp>
+
+using namespace boost::python;
+
+enum color { red = 1, green = 2, blue = 4 };
+
+color identity_(color x) { return x; }
+
+BOOST_PYTHON_MODULE(enums)
+{
+    enum_<color>("color")
+        .value("red", red)
+        .value("green", green)
+        .value("blue", blue)
+        ;
+    
+    def("identity", identity_);
+}
+
+

Interactive Python: +

+>>> from enums import *
+
+>>> identity(color.red)
+enums.color.red
+
+>>> identity(color.green)
+enums.color.green
+
+>>> identity(color.blue)
+enums.color.blue
+
+>>> identity(color(1))
+enums.color.red
+
+>>> identity(color(2))
+enums.color.green
+
+>>> identity(color(3))
+enums.color(3)
+
+>>> identity(color(4))
+enums.color.blue
+
+>>> identity(1)
+Traceback (most recent call last):
+  File "<stdin>", line 1, in ?
+TypeError: bad argument type for built-in operation
+
+
+ + Revised + + 03 October, 2002 + + +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header + <boost/python/exception_translator.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Functions
+ +
+
+
register_exception_translator
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

As described here, it + is important to make sure that exceptions thrown by C++ code do not pass + into the Python interpreter core. By default, Boost.Python translates all + C++ exceptions thrown by wrapped functions and module init functions into + Python, but the default translators are extremely limited: most C++ + exceptions will appear in Python as a RuntimeError + exception whose representation is + 'Unidentifiable C++ Exception'. To produce better + error messages, users can register additional exception translators as + described below.

+ +

Functions

+ +

register_exception_translator

+ +
+template<class ExceptionType, class Translate>
+void register_exception_translator(Translate const& translate);
+
+ +
+
Requires:
+ +
+ Translate is Copyconstructible, and + the following code must be well-formed: +
+void f(ExceptionType x) { translate(x); }
+
+ The expression translate(x) must either throw a C++ + exception, or a subsequent call to PyErr_Occurred() + must return 1. +
+ +

+ +

Effects: Adds a copy of translate to the sequence of + exception translators tried when Boost.Python catches an exception that + is about to pass into Python's core interpreter. The new translator + will get "first shot" at translating all exceptions matching the catch + clause shown above. Any subsequently-registered translators will be + allowed to translate the exception earlier. A translator which cannot + translate a given C++ exception can re-throw it, and it will be handled + by a translator which was registered earlier (or by the default + translator).
+
+ +

Example

+
+#include <boost/python/module.hpp>
+#include <boost/python/def.hpp>
+#include <boost/python/exception_translator.hpp>
+#include <exception>
+
+struct my_exception : std::exception
+{
+  char const* what() throw() { return "One of my exceptions"; }
+};
+
+void translate(my_exception const& e)
+{
+    // Use the Python 'C' API to set up an exception object
+    PyErr_SetString(PyExc_RuntimeError, e.what());
+}
+
+void something_which_throws()
+{
+    ...
+    throw my_exception();
+    ...
+}
+
+BOOST_PYTHON_MODULE(exception_translator_ext)
+{
+  using namespace boost::python;
+  register_exception_translator<my_exception>(&translate);
+  
+  def("something_which_throws", something_which_throws);
+}
+
+
+
+ +
+ +

Revised 03 October, 2002

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/extract.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class extract
+ +
+
+
Class extract + synopsis
+ +
Class extract + constructors and destructor
+ +
Class + extract observer functions
+
+
+
+
+ + +
Example
+
+
+ +

Introduction

+ +

Exposes a mechanism for extracting C++ object values from + generalized Python objects. Note that + extract<...> can also be used to + "downcast" an object to some specific ObjectWrapper. Because + invoking a mutable python type with an argument of the same type + (e.g. list([1,2]) typically makes a copy of + the argument object, this may be the only way to access the ObjectWrapper's + interface on the original object. + +

Classes

+ +

Class template extract

+ +

extract<T> can be used to extract a value of + an arbitrary C++ type from an instance of object. Two usages are supported: +

    +
  1. extract<T>(o) is a temporary object +which is implicitly convertible to T (explicit conversion +is also available through the object's function-call +operator). However, if no conversion is available which can convert +o to an object of type T, a Python +TypeError exception will be raised. + +
  2. extract<T> x(o); constructs an extractor +whose check() member function can be used to ask whether +a conversion is available without causing an exception to be thrown. +
+ +

Class template extract + synopsis

+
+namespace boost { namespace python
+{
+  template <class T>
+  struct extract
+  {
+      typedef unspecified result_type;
+
+      extract(PyObject*);
+      extract(object const&);
+
+      result_type operator()() const;
+      operator result_type() const;
+
+      bool check() const;
+  };
+}}
+
+ +

Class extract + constructors and destructor

+
+extract(PyObject* p);
+extract(object const&);
+
+ +
+
Requires: The first form requires that p is non-null.
+ +
Effects:Stores a pointer to the Python object managed + by its constructor argument. In particular, the reference + count of the object is not incremented. The onus is on the user + to be sure it is not destroyed before the extractor's conversion + function is called.
+
+ +

Class extract + observer functions

+
+result_type operator()() const;
+operator result_type() const;
+
+ +
+
Effects: Converts the stored pointer to + result_type, which is either T or + T const&. +
+ +
Returns: An object of result_type + corresponding to the one referenced by the stored pointer.
+ +
Throws: error_already_set + and sets a TypeError if no such conversion is + available. May also emit other unspecified exceptions thrown by + the converter which is actually used.
+
+ +
+bool check() const;
+
+ +
+ +
Postconditions: None. In particular, note that a + return value of true does not preclude an exception + being thrown from operator result_type() or + operator()().
+ +
Returns: false only if no conversion from the + stored pointer to T is available.
+ +
+ + +

Examples

+ +
+#include <cstdio>
+using namespace boost::python;
+int Print(str s)
+{ 
+   // extract a C string from the Python string object
+   char const* c_str = extract<char const*>(s);
+
+   // Print it using printf
+   std::printf("%s\n", c_str);
+
+   // Get the Python string's length and convert it to an int
+   return extract<int>(s.attr("__len__")())
+}
+
+ +The following example shows how extract can be used along with +class_<...> +to create and access an instance of a wrapped C++ class. + +
+struct X
+{
+   X(int x) : v(x) {}
+   int value() { return v; }
+ private:
+   int v;
+};
+
+BOOST_PYTHON_MODULE(extract_ext)
+{
+    object x_class(
+       class_<X>("X", init<int>())
+          .def("value", &X::value))
+          ;
+        
+    // Instantiate an X object through the Python interface. 
+    // Its lifetime is now managed by x_obj.
+    object x_obj = x_class(3);
+
+    // Get a reference to the C++ object out of the Python object
+    X const& x = extract<X&>(x_obj);
+    assert(x.value() == 3);
+}
+
+

Revised 30 September, 2002

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Headers <boost/python/init.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
init-expressions
+ +
Classes
+ +
+
+
Class template init
+ +
+
+
Class template + init synopsis
+ +
Class init + constructors
+ +
+
+ +
Class template + optional
+ +
+
+
Class template + optional synopsis
+
+
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

<boost/python/init.hpp> defines the interface for + exposing C++ constructors to Python as extension class + __init__ functions.

+ +

init-expressions

+ An init-expression is used to describe a family of + __init__ methods to be generated for an extension class, and + the result has the following properties: + +
+
+
docstring: An ntbs + whose value will bound to the method's __doc__ + attribute
+ +
keywords: A keyword-expression which will be + used to name (a trailing subsequence of) the arguments to the + generated __init__ function(s).
+ +
call policies: An instance of a model of CallPolicies.
+ +
argument types: An MPL sequence of C++ argument types + which will be used to construct the wrapped C++ object. An init + expression has one or more + valid prefixes which are given by a sequence of + prefixes of its argument types.
+
+
+ +

Classes

+ +

Class template init<T1 = + unspecified, T2 = + unspecified,...Tn = + unspecified>

+ +

A MPL sequence which + can be used to specify a family of one or more __init__ + functions. Only the last Ti supplied + may be an instantiation of optional<...>.

+ +

Class template init + synopsis

+
+namespace boost { namespace python
+{
+  template <T1 = unspecified,...Tn = unspecified>
+  struct init
+  {
+      init(char const* doc = 0);
+      template <class Keywords> init(Keywords const& kw, char const* doc = 0);
+      template <class Keywords> init(char const* doc, Keywords const& kw);
+
+      template <class CallPolicies>
+      unspecified operator[](CallPolicies const& policies) const
+  };
+}}
+
+ +

Class template init + constructors

+
+init(char const* doc = 0);
+template <class Keywords> init(Keywords const& kw, char const* doc = 0);
+template <class Keywords> init(char const* doc, Keywords const& kw);
+
+ +
+
Requires: If supplied, doc is an ntbs. If supplied, kw is the + result of a
+ +
Effects: The result is an init-expression whose + docstring is doc and whose keywords are + a reference to kw. If the first form is used, the + resulting expression's keywords are empty. The expression's + call policies are an instance of default_call_policies. + If Tn is optional<U1, U2,... + Um>, the + expression's valid prefixes are given by:
+ +
+
+ (T1, T2,...Tn-1), + (T1, T2,...Tn-1 + , U1), + (T1, T2,...Tn-1 + , U1, U2), + ...(T1, T2,...Tn-1 + , U1, U2,...Um). +
+ Otherwise, the expression has one valid prefix given by the + the template arguments the user specified. +
+
+ +

Class template init + observer functions

+
+template <class Policies>
+unspecified operator[](Policies const& policies) const
+
+ +
+
Requires: Policies is a model of CallPolicies.
+ +
Effects: Returns a new init-expression with all the same + properties as the init object except that its call + policies are replaced by a reference to + policies.
+
+ +

Class template optional<T1 + = unspecified, T2 = + unspecified,...Tn = + unspecified>

+ +

A MPL sequence which + can be used to specify the optional arguments to an __init__ + function.

+ +

Class template + optional synopsis

+
+namespace boost { namespace python
+{
+  template <T1 = unspecified,...Tn = unspecified>
+  struct optional {};
+}}
+
+ +

Example(s)

+ +

Given the C++ declarations:

+
+class Y;
+class X
+{
+ public:
+   X(int x, Y* y) : m_y(y) {}
+   X(double);
+ private:
+   Y* m_y;
+};
+
+ A corresponding Boost.Python extension class can be created with: +
+using namespace boost::python;
+
+class_<X>("X", "This is X's docstring.",
+          init<int,char const*>(args("x","y"), "X.__init__'s docstring")[
+                with_custodian_and_ward<1,3>()]
+          )
+   .def(init<double>())
+   ;
+
+
+ Revised + + 1 October, 2002 + + + +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/list.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class list
+ +
+
+
Class list + synopsis
+
+
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

Exposes a TypeWrapper for the Python + list + type.

+ +

Classes

+ +

Class list

+ +

Exposes the mapping + protocol of Python's built-in list type. The semantics + of the constructors and member functions defined below can be fully + understood by reading the TypeWrapper concept + definition. Since list is publicly derived from object, the public object + interface applies to list instances as well.

+ +

Class list + synopsis

+
+namespace boost { namespace python
+{
+  class list : public object
+  {
+   public:
+      list(); // new list
+
+      template <class T>
+      explicit list(T const& sequence);
+
+      template <class T>
+      void append(T const& x);
+
+      template <class T>
+      long count(T const& value) const;
+
+      template <class T>
+      void extend(T const& x);
+
+      template <class T>
+      long index(T const& x) const;
+
+      template <class T>
+      void insert(object const& index, T const& x); // insert object before index
+
+      object pop(); // remove and return item at index (default last)
+      object pop(long index);
+      object pop(object const& index);
+
+      template <class T>
+      void remove(T const& value);
+
+      void reverse(); // reverse *IN PLACE*
+
+      void sort(); //  sort *IN PLACE*; if given, cmpfunc(x, y) -> -1, 0, 1
+
+      template <class T>
+      void sort(T const& value);
+  };
+}}
+
+ +

Example

+
+using namespace boost::python;
+
+// Return the number of zeroes in the list
+long zeroes(list l)
+{
+   return l.count(0);
+}
+
+ +

Revised 1 October, 2002

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/long.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class long_
+ +
+
+
Class long_ + synopsis
+
+
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

Exposes a TypeWrapper for the Python + long + integer type.

+ +

Classes

+ +

Class long_

+ +

Exposes the numeric type + protocol of Python's built-in long type. The semantics + of the constructors and member functions defined below can be fully + understood by reading the TypeWrapper concept + definition. Since long_ is publicly derived from object, the public object + interface applies to long_ instances as well.

+ +

Class long_ + synopsis

+
+namespace boost { namespace python
+{
+  class long_ : public object
+  {
+   public:
+      long_(); // new long_
+
+      template <class T>
+      explicit long_(T const& rhs);
+
+      template <class T, class U>
+      long_(T const& rhs, U const& base);
+  };
+}}
+
+ +

Example

+
+namespace python = boost::python;
+
+// compute a factorial without overflowing
+python::long_ fact(long n)
+{
+   if (n == 0)
+      return python::long_(1);
+   else
+      return n * fact(n - 1);
+}
+
+ +

Revised 1 October, 2002

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/numeric.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class array
+ +
+
+
Class array + synopsis
+ +
Class array + observer functions
+ +
Class array + static functions
+
+
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

Exposes a TypeWrapper for the Python + array + type.

+ +

Classes

+ +

Class array

+ +

Provides access to the array types of Numerical Python's Numeric and NumArray modules. With + the exception of the functions documented below, the semantics of the constructors and + member functions defined below can be fully understood by reading the TypeWrapper concept + definition. Since array is publicly derived from object, the public object + interface applies to array instances as well.

+ +

The default behavior is to use + Numeric.ArrayType as the associated Python type if the + Numeric module is installed in the default location. + Otherwise it falls back to use numarray.NDArray. If neither + extension module is installed, conversions to arguments of type + numeric::array will cause overload resolution to reject the + overload, and other attempted uses of numeric::array will raise an appropriate Python exception. + The associated Python type can be set manually using the set_module_and_type(...) static + function.

+ +

Class array + synopsis

+
+namespace boost { namespace python { namespace numeric
+{
+   class array : public object
+   {
+    public:
+      object astype();
+      template <class Type>
+      object astype(Type const& type_);
+
+      template <class Type>
+      object new_(Type const& type_) const;
+
+      template <class Sequence> 
+      void resize(Sequence const& x);
+      void resize(long x1);
+      void resize(long x1, long x2);
+      ...
+      void resize(long x1, long x2,...long xn);
+
+      template <class Sequence> 
+      void setshape(Sequence const& x);
+      void setshape(long x1);
+      void setshape(long x1, long x2);
+      ...
+      void setshape(long x1, long x2,...long xn);
+
+      template <class Indices, class Values>
+      void put(Indices const& indices, Values const& values);
+
+      template <class Sequence>
+      object take(Sequence const& sequence, long axis = 0);
+
+      template <class File>
+      void tofile(File const& f) const;
+
+      object factory();
+      template <class Buffer>
+      object factory(Buffer const&);
+      template <class Buffer, class Type>
+      object factory(Buffer const&, Type const&);
+      template <class Buffer, class Type, class Shape>
+      object factory(Buffer const&, Type const&, Shape const&, bool copy = true, bool savespace = false);
+      template <class Buffer, class Type, class Shape>
+      object factory(Buffer const&, Type const&, Shape const&, bool copy, bool savespace, char typecode);
+
+      template <class T1>
+      explicit array(T1 const& x1);
+      template <class T1, class T2>
+      explicit array(T1 const& x1, T2 const& x2);
+      ...
+      template <class T1, class T2,...class Tn>
+      explicit array(T1 const& x1, T2 const& x2,...Tn const& xn);
+
+      static void set_module_and_type();
+      static void set_module_and_type(char const* package_path = 0, char const* type_name = 0);
+
+      object argmax(long axis=-1);
+
+      object argmin(long axis=-1);
+
+      object argsort(long axis=-1);
+
+      void byteswap();
+
+      object copy() const;
+
+      object diagonal(long offset = 0, long axis1 = 0, long axis2 = 1) const;
+
+      void info() const;
+
+      bool is_c_array() const;
+      bool isbyteswapped() const;
+      void sort();
+      object trace(long offset = 0, long axis1 = 0, long axis2 = 1) const;
+      object type() const;
+      char typecode() const;
+      
+      object getflat() const;
+      long getrank() const;
+      object getshape() const;
+      bool isaligned() const;
+      bool iscontiguous() const;
+      long itemsize() const;
+      long nelements() const;
+      object nonzero() const;
+   
+      void ravel();
+   
+      object repeat(object const& repeats, long axis=0);
+   
+      void setflat(object const& flat);
+   
+      void swapaxes(long axis1, long axis2);
+   
+      str tostring() const;
+   
+      void transpose(object const& axes = object());
+   
+      object view() const;
+  };
+}}}
+
+ +

Class array observer + functions

+
+object factory();
+template <class Buffer>
+object factory(Buffer const&);
+template <class Buffer, class Type>
+object factory(Buffer const&, Type const&);
+template <class Buffer, class Type, class Shape>
+object factory(Buffer const&, Type const&, Shape const&, bool copy = true, bool savespace = false);
+template <class Buffer, class Type, class Shape>
+object factory(Buffer const&, Type const&, Shape const&, bool copy, bool savespace, char typecode);
+
+ These functions map to the underlying array type's array() + function family. They are not called "array" because of the + C++ limitation that you can't define a member function with the same name + as its enclosing class. +
+template <class Type>
+object new_(Type const&) const;
+
+ This function maps to the underlying array type's new() + function. It is not called "new" because that is a keyword + in C++. + +

Class array static + functions

+
+static void set_module_and_type(char const* package_path, char const* type_name);
+static void set_module_and_type();
+
+ +
+
Requires: package_path and + type_name, if supplied, is an ntbs.
+ +
Effects: The first form sets the package path of the module + which supplies the type named by type_name to + package_path. The second form restores the default search behavior. The associated Python + type will be searched for only the first time it is needed, and + thereafter the first time it is needed after an invocation of + set_module_and_type.
+
+ +

Example

+
+#include <boost/python/numeric.hpp>
+#include <boost/python/tuple.hpp>
+
+// sets the first element in a 2d numeric array
+void set_first_element(numeric::array& y, double value)
+{
+    y[make_tuple(0,0)] = value;
+}
+
+ +

Revised 03 October, 2002

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/object.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Types
+ +
+
+
slice_nil
+
+
+ +
Classes
+ +
+
+
Class + const_attribute_policies
+ +
+
+
Class + const_attribute_policies synopsis
+ +
Class + const_attribute_policies static functions
+
+
+ +
Class + attribute_policies
+ +
+
+
Class + attribute_policies synopsis
+ +
Class + attribute_policies static functions
+
+
+ +
Class + const_item_policies
+ +
+
+
Class + const_item_policies synopsis
+ +
Class + const_item_policies static functions
+
+
+ +
Class + item_policies
+ +
+
+
Class + item_policies synopsis
+ +
Class + item_policies static functions
+
+
+ +
Class + const_slice_policies
+ +
+
+
Class + const_slice_policies synopsis
+ +
Class + const_slice_policies static functions
+
+
+ +
Class + slice_policies
+ +
+
+
Class + slice_policies synopsis
+ +
Class + slice_policies static functions
+
+
+ +
Class + object_operators
+ +
+
+
Class + object_operators synopsis
+ +
Class + object_operators observer functions
+
+
+ +
Class object
+ +
+
+
Class object + synopsis
+ +
Class object + constructors and destructor
+ +
Class template + object modifier functions
+ +
Class template + object observer functions
+
+
+ +
Class template + proxy
+ +
+
+
Class template + proxy synopsis
+ +
Class template + proxy modifier functions
+ +
Class template + proxy observer functions
+
+
+
+
+ +
Functions
+ +
+
+
del
+ +
comparisons
+ +
binary operations
+ +
assignment operations
+
+ +
+
operators
+
+
+ +
Example
+
+
+ +

Introduction

+ +

Exposes the generic Python object wrapper class object, + and related classes. In order to avoid some potenential problems with + argument-dependent lookup and the generalized operators defined on + object, all these facilities are defined in + namespace boost::python::api, and object + is imported into namespace boost::python with a + using-declaration.

+ +

Types

+ +

+
+enum slice_nil { _ };
+
+ A type that can be used to get the effect of leaving out an index in a + Python slice expression: +
+>>> x[:-1]
+
+ C++ equivalent: +
+x.slice(_,-1)
+
+ +

Classes

+ + +

Class + const_attribute_policies

+ +

The policies which are used for proxies representing an attribute + access to a const object.

+ +

Class + const_attribute_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct const_attribute_policies
+  {
+      typedef char const* key_type;
+      static object get(object const& target, char const* key);
+  };
+}}}
+
+ +

Class + const_attribute_policies static functions

+
+static object get(object const& target, char const* key);
+
+ +
+
Requires: key is an ntbs.
+ +
Effects: accesses the attribute of target named + by key.
+ +
Returns: An object managing the result of the + attribute access.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ +

Class + attribute_policies

+ +

The policies which are used for proxies representing an attribute + access to a mutable object.

+ +

Class + attribute_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct attribute_policies : const_attribute_policies
+  {
+      static object const& set(object const& target, char const* key, object const& value);
+      static void del(object const&target, char const* key);
+  };
+}}}
+
+ +

Class + attribute_policies static functions

+
+static object const& set(object const& target, char const* key, object const& value);
+
+ +
+
Requires: key is an ntbs.
+ +
Effects: sets the attribute of target named by + key to value.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+
+static void del(object const&target, char const* key);
+
+ +
+
Requires: key is an ntbs.
+ +
Effects: deletes the attribute of target named + by key.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ + + +

Class + const_item_policies

+ +

The policies which are used for proxies representing an item access + (via the Python bracket operators []) to a + const object.

+ +

Class + const_item_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct const_item_policies
+  {
+      typedef object key_type;
+      static object get(object const& target, object const& key);
+  };
+}}}
+
+ +

Class + const_item_policies static functions

+
+static object get(object const& target, object const& key);
+
+ +
+
Effects: accesses the item of target specified + by key.
+ +
Returns: An object managing the result of the + item access.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ +

Class + item_policies

+ +

The policies which are used for proxies representing an item access + (via the Python bracket operators []) to a mutable + object.

+ +

Class + item_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct item_policies : const_item_policies
+  {
+      static object const& set(object const& target, object const& key, object const& value);
+      static void del(object const& target, object const& key);
+  };
+}}}
+
+ +

Class + item_policies static functions

+
+static object const& set(object const& target, object const& key, object const& value);
+
+ +
+
Effects: sets the item of target specified by + key to value.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+
+static void del(object const& target, object const& key);
+
+ +
+
Effects: deletes the item of target specified + by key.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ + + +

Class + const_slice_policies

+ +

The policies which are used for proxies representing an slice access + (via the Python slice notation + [x:y]) to a + const object.

+ +

Class + const_slice_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct const_slice_policies
+  {
+      typedef std::pair<handle<>, handle<> > key_type;
+      static object get(object const& target, key_type const& key);
+  };
+}}}
+
+ +

Class + const_slice_policies static functions

+
+static object get(object const& target, key_type const& key);
+
+ +
+
Effects: accesses the slice of target specified + by key.
+ +
Returns: An object managing the result of the + slice access.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ +

Class + slice_policies

+ +

The policies which are used for proxies representing an slice access + to a mutable object.

+ +

Class + slice_policies synopsis

+
+namespace boost { namespace python { namespace api
+{
+  struct slice_policies : const_slice_policies
+  {
+      static object const& set(object const& target, key_type const& key, object const& value);
+      static void del(object const& target, key_type const& key);
+  };
+}}}
+
+ +

Class + slice_policies static functions

+
+static object const& set(object const& target, key_type const& key, object const& value);
+
+ +
+
Effects: sets the slice of target specified by + key to value.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+
+static void del(object const& target, key_type const& key);
+
+ +
+
Effects: deletes the slice of target specified + by key.
+ +
Throws: error_already_set if a + Python exception is raised.
+
+ + +

Class template + object_operators<U>

+ +

This is the base class of object and its + proxy template used to supply common interface: member + functions, and operators which must be defined within the class body. Its + template parameter U is expected to be a class derived from + object_operators<U>. In practice users should never + use this class directly, but it is documented here because it supplies + important interface to object and its proxies.

+ +

Class template + object_operators synopsis

+
+namespace boost { namespace python { namespace api
+{
+  template <class U>
+  class object_operators
+  {
+   public:
+      // function call
+      //
+      object operator()() const;
+
+      template <class A0>
+      object operator()(A0 const&) const;
+      template <class A0, class A1>
+      object operator()(A0 const&, A1 const&) const;
+      ...
+      template <class A0, class A1,...class An>
+      object operator()(A0 const&, A1 const&,...An const&) const;
+
+      // truth value testing
+      //
+      typedef unspecified bool_type;
+      operator bool_type() const;
+
+      // Attribute access
+      //
+      proxy<const_object_attribute> attr(char const*) const;
+      proxy<object_attribute> attr(char const*);
+
+      // item access
+      //
+      template <class T>
+      proxy<const_object_item> operator[](T const& key) const;
+    
+      template <class T>
+      proxy<object_item> operator[](T const& key);
+
+      // slicing
+      //
+      template <class T, class V>
+      proxy<const_object_slice> slice(T const& start, V const& end) const
+    
+      template <class T, class V>
+      proxy<object_slice> slice(T const& start, V const& end);
+  };
+}}}
+
+ +

Class template + object_operators observer functions

+
+object operator()() const;
+template <class A0>
+object operator()(A0 const&) const;
+template <class A0, class A1>
+object operator()(A0 const&, A1 const&) const;
+...
+template <class A0, class A1,...class An>
+object operator()(A0 const& a1, A1 const& a2,...An const& aN) const;
+
+ +
+
Effects: + call<object>(object(*static_cast<U*>(this)).ptr(), a1, + a2,...aN)
+
+
+operator bool_type() const;
+
+ +
+
Effects: Tests truth value of *this.
+ +
Returns: + call<object>(object(*static_cast<U*>(this)).ptr(), a1, + a2,...aN)
+
+
+proxy<const_object_attribute> attr(char const* name) const;
+proxy<object_attribute> attr(char const* name);
+
+ +
+
Requires: name is an ntbs.
+ +
Effects: accesses the named attribute of + *this.
+ +
Returns: a proxy object which binds + object(*static_cast<U*>(this)) as its target, and + name as its key.
+
+
+template <class T>
+proxy<const_object_item> operator[](T const& key) const;
+template <class T>
+proxy<object_item> operator[](T const& key);
+
+ +
+
Effects: accesses the item of *this indicated + by key.
+ +
Returns: a proxy object which binds + object(*static_cast<U*>(this)) as its target, and + object(key) as its key.
+
+
+template <class T, class V>
+proxy<const_object_slice> slice(T const& start; start, V const& finish) const
+template <class T, class V>
+proxy<object_slice> slice(T const& start; start, V const& finish);
+
+ +
+
Effects: accesses the slice of *this indicated + by std::make_pair(object(start), object(finish)).
+ +
Returns: a proxy object which binds + object(*static_cast<U*>(this)) as its target, and + std::make_pair(object(start), object(finish)) as its + key.
+
+ + +

Class object

+ +

The intention is that object acts as much like a + Python variable as possible. Thus expressions you'd expect to work + in Python should generally work in the same way from C++. Most of + object's interface is provided by its base class + object_operators<object>, + and the free functions defined in this + header. +

+ +

Class object + synopsis

+
+namespace boost { namespace python { namespace api
+{
+  class object : public object_operators<object>
+  {
+   public:
+      object();
+
+      object(object const&);
+      
+      template <class T>
+      explicit object(T const& x);
+
+      ~object();
+
+      object& operator=(object const&); 
+
+      PyObject* ptr() const;
+  };
+}}}
+
+ +

Class object + constructors and destructor

+
+object();
+
+ +
+
Effects: Constructs an object managing a reference to the + Python None object.
+ +
Throws: nothing.
+
+
+template <class T>
+explicit object(T const& x);
+
+ +
+
Effects: converts x to python and manages a + reference to it.
+ +
Throws: error_already_set and sets a Python + TypeError exception if no such conversion is + possible.
+
+
+~object();
+
+ +
+
Effects: decrements the reference count of the + internally-held object.
+
+ +

Class object + modifiers

+
+object& operator=(object const& rhs); 
+
+ +
+
Effects: increments the reference count of the object held + by rhs and decrements the reference count of the object + held by *this.
+
+ +

Class object + observers

+
+PyObject* ptr() const;
+
+ +
+
Returns: a pointer to the internally-held Python + object.
+
+ + +

Class template proxy

+ +

This template is instantiated with various Policies described in this + document in order to implement attribute, item, and slice access for + object. It stores an object of type + Policies::key_type.

+ +

Class template proxy + synopsis

+
+namespace boost { namespace python { namespace api
+{
+  template <class Policies>
+  class proxy : public object_operators<proxy<Policies> >
+  {
+   public:
+      operator object() const;
+
+      proxy const& operator=(proxy const&) const;
+      template <class T>
+      inline proxy const& operator=(T const& rhs) const;
+      
+      void del() const;
+
+      template <class R>
+      proxy operator+=(R const& rhs);
+      template <class R>
+      proxy operator-=(R const& rhs);
+      template <class R>
+      proxy operator*=(R const& rhs);
+      template <class R>
+      proxy operator/=(R const& rhs);
+      template <class R>
+      proxy operator%=(R const& rhs);
+      template <class R>
+      proxy operator<<=(R const& rhs);
+      template <class R>
+      proxy operator>>=(R const& rhs);
+      template <class R>
+      proxy operator&=(R const& rhs);
+      template <class R>
+      proxy operator|=(R const& rhs);
+  };
+}}}
+
+ +

Class template proxy + observer functions

+
+operator object() const;
+
+ +
+
Effects: applies + Policies::get(target, key + ) with the proxy's target and key objects.
+
+ +

Class template proxy + modifier functions

+
+proxy const& operator=(proxy const& rhs) const;
+template <class T>
+inline proxy const& operator=(T const& rhs) const;
+
+ +
+
Effects: + Policies::set(target, key + , object(rhs)) with the proxy's target and key + objects.
+
+
+template <class R>
+proxy operator+=(R const& rhs);
+template <class R>
+proxy operator-=(R const& rhs);
+template <class R>
+proxy operator*=(R const& rhs);
+template <class R>
+proxy operator/=(R const& rhs);
+template <class R>
+proxy operator%=(R const& rhs);
+template <class R>
+proxy operator<<=(R const& rhs);
+template <class R>
+proxy operator>>=(R const& rhs);
+template <class R>
+proxy operator&=(R const& rhs);
+template <class R>
+proxy operator|=(R const& rhs);
+
+ +
+
Effects: for a given operator@=, + object(*this) @= rhs;
+
Returns: *this
+
+
+void del() const;
+
+ +
+
Effects: + Policies::del(target, key + ) with the proxy's target and key objects.
+
+ + +

Functions

+
+template <class T>
+void del(proxy<T> const& x);
+
+ +
+
Effects: x.del()
+
+
+
+template<class L,class R> bool operator>(L const&l,R const&r);
+template<class L,class R> bool operator>=(L const&l,R const&r);
+template<class L,class R> bool operator<(L const&l,R const&r);
+template<class L,class R> bool operator<=(L const&l,R const&r);
+template<class L,class R> bool operator==(L const&l,R const&r);
+template<class L,class R> bool operator!=(L const&l,R const&r);
+
+ +
+
Effects: returns the result of applying the operator to + object(l) and object(r), respectively, in + Python.
+
+
+
+template<class L,class R> object operator+(L const&l,R const&r);
+template<class L,class R> object operator-(L const&l,R const&r);
+template<class L,class R> object operator*(L const&l,R const&r);
+template<class L,class R> object operator/(L const&l,R const&r);
+template<class L,class R> object operator%(L const&l,R const&r);
+template<class L,class R> object operator<<(L const&l,R const&r);
+template<class L,class R> object operator>>(L const&l,R const&r);
+template<class L,class R> object operator&(L const&l,R const&r);
+template<class L,class R> object operator^(L const&l,R const&r);
+template<class L,class R> object operator|(L const&l,R const&r);
+
+ +
+
Effects: returns the result of applying the operator to + object(l) and object(r), respectively, in + Python.
+
+
+
+template<class R> object& operator+=(object&l,R const&r);
+template<class R> object& operator-=(object&l,R const&r);
+template<class R> object& operator*=(object&l,R const&r);
+template<class R> object& operator/=(object&l,R const&r);
+template<class R> object& operator%=(object&l,R const&r);
+template<class R> object& operator<<=(object&l,R const&r)
+template<class R> object& operator>>=(object&l,R const&r);
+template<class R> object& operator&=(object&l,R const&r);
+template<class R> object& operator^=(object&l,R const&r);
+template<class R> object& operator|=(object&l,R const&r);
+
+ +
+
Effects: assigns to l the result of applying the + corresponding Python inplace operator to l and + object(r), respectively.
+ +
Returns: l.
+
+ +

Example

+ Python code: +
+def sum_items(seq):
+   result = 0
+   for x in seq:
+      result += x
+   return result
+
+ C++ version: +
+object sum_items(object seq)
+{
+   object result = object(0);
+   for (int i = 0; i < seq.attr("__len__")(); ++i)
+      result += seq[i];
+   return result;
+}
+
+ +

Revised + + 02 October, 2002 + +

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/overloads.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
overload-dispatch-expressions
+ +
OverloadDispatcher concept
+ +
Macros
+ +
+
+
BOOST_PYTHON_FUNCTION_OVERLOADS
+ +
BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

Defines facilities for generating families of overloaded Python + functions and extension class methods from C++ functions and + member functions with default arguments, or from similar families + of C++ overloads

+ +

overload-dispatch-expressions

+ +

+ An overload-dispatch-expression is used to describe a + family of overloaded methods to be generated for an extension + class. It has the following properties: + +

+
+
docstring: An ntbs + whose value will bound to the methods' __doc__ + attribute
+ +
keywords: A keyword-expression which + will be used to name (a trailing subsequence of) the arguments + to the generated methods.
+ +
call policies: An instance of some type which models CallPolicies.
+ +
minimum arity + The minimum number of arguments to be accepted by a generated + method overload.
+ +
maximum arity + The maximum number of arguments to be accepted by a generated + method overload.
+
+
+ +

OverloadDispatcher Concept

+ + An OverloadDispatcher X is a class which has a + minimum arity and a maximum arity, and for which + the following following are valid overload-dispatch-expressions, + with the same minimum and maximum arity as the OverloadDispatcher. + +
+X()
+X(docstring)
+X(docstring, keywords)
+X(keywords, docstring)
+X()[policies]
+X(docstring)[policies]
+X(docstring, keywords)[policies]
+X(keywords, docstring)[policies]
+
+ + + + + + +

Macros

+ +

BOOST_PYTHON_FUNCTION_OVERLOADS(name, func_id, min_args, max_args)

+ Expands to the definition of an OverloadDispatcher called + name in the current scope which can be used to + generate the following function invocation: +
+func_id(a1, a2,...ai);
+
+ + for all min_args <= i <= max_args. + +

BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(name, member_name, min_args, max_args)

+ + Expands to the definition of an OverloadDispatcher called + name in the current scope which can be used to + generate the following function invocation: +
+x.member_name(a1, a2,...ai);
+
+ + for all min_args <= i <= + max_args, where x is a reference to an + object of class type. + +

Example(s)

+ +
+#include <boost/python/module.hpp>
+#include <boost/python/def.hpp>
+#include <boost/python/args.hpp>
+#include <boost/python/tuple.hpp>
+#include <boost/python/class.hpp>
+#include <boost/python/overloads.hpp>
+#include <boost/python/return_internal_reference.hpp>
+
+using namespace boost::python;
+
+tuple f(int x = 1, double y = 4.25, char const* z = "wow")
+{
+    return make_tuple(x, y, z);
+}
+
+BOOST_PYTHON_FUNCTION_OVERLOADS(f_overloads, f, 0, 3)
+
+stryct Y {};
+struct X
+{
+    Y& f(int x, double y = 4.25, char const* z = "wow")
+    {
+        return inner;
+    }
+    Y inner;
+};
+
+BOOST_PYTHON_MEMBER_FUNCTION_OVERLOADS(X_f_overloads, X::f, 1, 3)
+
+BOOST_PYTHON_MODULE(args_ext)
+{
+    def("f", f, args("x", "y", "z")
+        , "This is f's docstring"
+        );
+
+    
+    class_<Y>("Y")
+        ;
+            
+    class_<X>("X", "This is X's docstring")
+        .def("f1", &X::f, 
+                X_f_overloads(args("x", "y", "z"),
+                              "f's docstring"
+                                  )[return_internal_reference<>()])
+        ;
+}
+
+ +

Revised + + 01 October, 2002 + +

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

+

+ + 		+

Boost.Python

+ +

Header <boost/python/pointee.hpp>

+
+
+ +

Contents

+ +
+
Introduction + +
Classes + +
+
+
Class Templatepointee + +
+
+
Class Template + pointee synopsis +
+
+ +
Example +
+
+ +

Introduction

+ +

<boost/python/pointee.hpp> introduces a + traits metafunction + template pointee<T> which can be used to extract the "pointed-to" type from the type of a pointer or smart pointer. + +

Classes

+ +

Class Template pointee<class T>

+ +

pointee<T> is used by the class_<...> + template to deduce the type being held when a pointer or smart + pointer type is used as its HeldType argument. + +

Class Template + pointee synopsis

+
+namespace boost { namespace python
+{
+   template <class T> struct pointee
+   {
+      typedef T::element_type type;
+   };
+
+   // specialization for pointers
+   template <T> struct pointee<T*>
+   {
+      typedef T type;
+   };
+}
+
+ + +

Example

+ +Given a 3rd-party smart pointer type +smart_pointer<T>, one might partially specialize +pointee<smart_pointer<T> > so that it can be +used as the HeldType for a class wrapper: + +
+#include <boost/python/pointee.hpp>
+#include <boost/python/class.hpp>
+#include <third_party_lib.hpp>
+
+namespace boost { namespace python
+{
+  template <class T> struct pointee<smart_pointer<T> >
+  {
+     typedef T type;
+  };
+}}
+
+BOOST_PYTHON_MODULE(pointee_demo)
+{
+   class_<third_party_class, smart_pointer<third_party_class> >("third_party_class")
+      .def(...)
+      ...
+      ;
+}
+
+ +

Revised + + 03 October, 2002 + + + +

© Copyright Dave + Abrahams 2002. All Rights Reserved. + diff --git a/doc/v2/scope.html b/doc/v2/scope.html new file mode 100644 index 00000000..17450645 --- /dev/null +++ b/doc/v2/scope.html @@ -0,0 +1,153 @@ + + + + + + + + + Boost.Python - <boost/python/scope.hpp> + + + + + + + + + +
+

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/scope.hpp>

+
+

+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class scope
+ +
+
+
Class scope + synopsis
+ +
Class scope + constructors and destructor
+
+
+
+
+ +
Example
+
+
+ +

Introduction

+ +

Defines facilities for querying and controlling the Python scope + (namespace) which will contain new wrapped classes and functions.

+ +

Classes

+ +

Class scope

+ +

The scope class has an associated global Python object + which controls the Python namespace in which new extension classes and + wrapped functions will be defined as attributes. Default-constructing a + new scope object binds that object to the associated Python + object. Constructing a is associated with , and

+ +

Class scope + synopsis

+
+namespace boost { namespace python
+{
+  class scope : public object, private noncopyable
+  {
+   public:
+      scope(object const&);
+      scope();
+      ~scope()
+  };
+}}
+
+ +

Class scope constructors + and destructor

+
+scope(object const& x);
+
+ Stores a reference to the current associated scope object, and sets the + associated scope object to the one referred to by x.ptr(). + The object base class is initialized with x. +
+scope();
+
+ Stores a reference to the current associated scope object. The + object base class is initialized with the current associated + scope object. Outside any module initialization function, the current + associated Python object is None. +
+~scope()
+
+ Sets the current associated Python object to the stored object. + +

Example

+ The following example shows how scope setting can be used to define + nested classes. + +

C++ Module definition:

+
+#include <boost/python/class.hpp>
+#include <boost/python/scope.hpp>
+using namespace boost::python;
+
+struct X
+{
+  void f();
+
+  struct Y { int g() { return 0; } };
+};
+
+BOOST_PYTHON_MODULE(nested)
+{
+   scope outer
+       = class_<X>("X")
+            .def("f", &X::f)
+            ;
+   class_<Y>("Y")
+      .def("g", &Y::g)
+      ;
+}
+
+ Interactive Python: +
+>>> import nested
+>>> y = nested.X.Y()
+>>> y.g()
+0
+
+ +

Revised 03 October, 2002

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/str.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class str
+ +
+
+
Class str + synopsis
+
+
+
+
+ +
Example(s)
+
+
+ +

Introduction

+ +

Exposes a TypeWrapper for the Python + str + type.

+ +

Classes

+ +

Class str

+ +

Exposes the string + methods of Python's built-in str type. The + semantics of the constructors and member functions defined below + can be fully understood by reading the TypeWrapper concept + definition. Since str is publicly derived from + object, the + public object interface applies to str instances as + well.

+ +

Class str + synopsis

+
+namespace boost { namespace python
+{
+  class str : public object
+  {
+   public:
+      str(); // new str
+
+      str(const char* s); // new str
+
+      template <class T>
+      explicit str(T const& other);
+
+      str capitalize() const;
+
+      template <class T>
+      str center(T const& width) const;
+
+      template<class T>
+      long count(T const& sub) const;
+      template<class T1, class T2>
+      long count(T1 const& sub,T2 const& start) const;
+      template<class T1, class T2, class T3>
+      long count(T1 const& sub,T2 const& start, T3 const& end) const;
+
+      object decode() const;
+      template<class T>
+      object decode(T const& encoding) const;
+      template<class T1, class T2>
+      object decode(T1 const& encoding, T2 const& errors) const;
+
+      object encode() const;
+      template <class T>
+      object encode(T const& encoding) const;
+      template <class T1, class T2>
+      object encode(T1 const& encoding, T2 const& errors) const;
+
+      template <class T>
+      bool endswith(T const& suffix) const;
+      template <class T1, class T2>
+      bool endswith(T1 const& suffix, T2 const& start) const;
+      template <class T1, class T2, class T3>
+      bool endswith(T1 const& suffix, T2 const& start, T3 const& end) const;
+
+      str expandtabs() const;
+      template <class T>
+      str expandtabs(T const& tabsize) const;
+
+      template <class T>
+      long find(T const& sub) const;
+      template <class T1, class T2>
+      long find(T1 const& sub, T2 const& start) const;
+      template <class T1, class T2, class T3>
+      long find(T1 const& sub, T2 const& start, T3 const& end) const;
+
+      template <class T>
+      long index(T const& sub) const;
+      template <class T1, class T2>
+      long index(T1 const& sub, T2 const& start) const;
+      template <class T1, class T2, class T3>
+      long index(T1 const& sub, T2 const& start, T3 const& end) const;
+
+      bool isalnum() const;
+      bool isalpha() const;
+      bool isdigit() const;
+      bool islower() const;
+      bool isspace() const;
+      bool istitle() const;
+      bool isupper() const;
+
+      template <class T>
+      str join(T const& sequence) const;
+
+      template <class T>
+      str ljust(T const& width) const;
+
+      str lower() const;
+      str lstrip() const;
+
+      template <class T1, class T2>
+      str replace(T1 const& old, T2 const& new_) const;
+      template <class T1, class T2, class T3>
+      str replace(T1 const& old, T2 const& new_, T3 const& maxsplit) const;
+
+      template <class T>
+      long rfind(T const& sub) const;
+      template <class T1, class T2>
+      long rfind(T1 const& sub, T2 const& start) const;
+      template <class T1, class T2, class T3>
+      long rfind(T1 const& sub, T2 const& start, T3 const& end) const;
+
+      template <class T>
+      long rindex(T const& sub) const;
+      template <class T1, class T2>
+      long rindex(T1 const& sub, T2 const& start) const;
+      template <class T1, class T2, class T3>
+      long rindex(T1 const& sub, T2 const& start, T3 const& end) const;
+
+      template <class T>
+      str rjust(T const& width) const;
+
+      str rstrip() const;
+
+      list split() const; 
+      template <class T>
+      list split(T const& sep) const;
+      template <class T1, class T2>
+      list split(T1 const& sep, T2 const& maxsplit) const;
+
+      list splitlines() const;
+      template <class T>
+      list splitlines(T const& keepends) const;
+
+      template <class T>
+      bool startswith(T const& prefix) const;
+      template <class T1, class T2>
+      bool startswidth(T1 const& prefix, T2 const& start) const;
+      template <class T1, class T2, class T3>
+      bool startswidth(T1 const& prefix, T2 const& start, T3 const& end) const;
+
+      str strip() const;
+      str swapcase() const;
+      str title() const;
+
+      template <class T>
+      str translate(T const& table) const;
+      template <class T1, class T2>
+      str translate(T1 const& table, T2 const& deletechars) const;
+
+      str upper() const;
+  };
+}}
+
+ +

Example

+
+using namespace boost::python;
+str remove_angle_brackets(str x)
+{
+  return x.strip('<').strip('>');
+}
+
+ +

Revised 3 October, 2002

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

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

C++ Boost

+ 		+

Boost.Python

+ +

Header <boost/python/tuple.hpp>

+
+
+ +

Contents

+ +
+
Introduction
+ +
Classes
+ +
+
+
Class tuple
+ +
+
+
Class tuple + synopsis
+
+
+
+
+ +
Functions
+ +
+
+
make_tuple
+
+
+ +
Example
+
+
+ +

Introduction

+ +

Exposes a TypeWrapper for the Python + + tuple type.

+ +

Classes

+ +

Class tuple

+ +

Exposes the interface of Python's built-in tuple type. + The semantics of the constructors and member functions defined below can + be fully understood by reading the TypeWrapper concept + definition. Since tuple is publicly derived from object, the public object + interface applies to tuple instances as well.

+ +

Class tuple + synopsis

+
+namespace boost { namespace python
+{
+   class tuple : public object
+   {
+      // tuple() -> an empty tuple
+      tuple();
+
+      // tuple(sequence) -> tuple initialized from sequence's items
+      template <class T>
+      explicit tuple(T const& sequence)
+  };
+}}
+
+ +

Functions

+ +

make_tuple

+
+namespace boost { namespace python
+{
+  tuple make_tuple();
+
+  template <class A0>
+  tuple make_tuple(A0 const& a0);
+
+  template <class A0, class A1>
+  tuple make_tuple(A0 const& a0, A1 const& a1);
+  ...
+  template <class A0, class A1,...class An> 
+  tuple make_tuple(A0 const& a0, A1 const& a1,...An const& an);
+}}
+
+ Constructs a new tuple object composed of object(a0), + object(a0),...object(an). + +

Example

+
+using namespace boost::python;
+tuple head_and_tail(object sequence)
+{
+    return make_tuple(sequence[0],sequence[-1]);
+}
+
+ +

Revised 03 October, 2002

+ +

© Copyright Dave Abrahams 2002. All Rights + Reserved.

+ + + diff --git a/include/boost/python/detail/overloads_fwd.hpp b/include/boost/python/detail/overloads_fwd.hpp new file mode 100644 index 00000000..94ec503f --- /dev/null +++ b/include/boost/python/detail/overloads_fwd.hpp @@ -0,0 +1,19 @@ +// 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. +#ifndef OVERLOADS_FWD_DWA2002101_HPP +# define OVERLOADS_FWD_DWA2002101_HPP + +namespace boost { namespace python { namespace detail { + +// forward declarations +struct overloads_base; + +template +inline void define_with_defaults(char const* name, OverloadsT const&, NameSpaceT&, SigT const&); + +}}} // namespace boost::python::detail + +#endif // OVERLOADS_FWD_DWA2002101_HPP diff --git a/include/boost/python/overloads.hpp b/include/boost/python/overloads.hpp new file mode 100644 index 00000000..50fc2497 --- /dev/null +++ b/include/boost/python/overloads.hpp @@ -0,0 +1,12 @@ +// 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. +#ifndef OVERLOADS_DWA2002101_HPP +# define OVERLOADS_DWA2002101_HPP + +# include +# include + +#endif // OVERLOADS_DWA2002101_HPP